راه‌اندازی پروژه Xcode

پس‌از فعال کردن صورت‌حساب و ایجاد کلید میانای برنامه‌سازی کاربردی، پروژه Xcode را که برای توسعه برنامه‌تان استفاده می‌کنید راه‌اندازی کنید.

یادداشت‌های انتشار برای هر انتشار دردسترس است.

مرحله ۱: نصب نرم‌افزار موردنیاز

برای ساختن پروژه بااستفاده از Maps SDK for iOS، موارد زیر را بارگیری و نصب کنید:

• Xcode نسخه ۲۶.۰ یا بالاتر

مرحله ۲: ایجاد پروژه Xcode و نصب کیت توسعه نرم‌افزار Google Maps برای iOS

توجه: کیت توسعه نرم‌افزار Google Maps برای iOS به‌طور میانگین ۵٫۷ مگابایت به اندازه IPA برنامه‌هایی که برای دستگاه‌های خاص ساخته شده‌اند اضافه می‌کند. اندازه بارگیری برای برنامه‌های جهانی ممکن است بزرگ‌تر باشد.

اندازه نصب کیت توسعه نرم‌افزار (SDK) متفاوت است. برای مثال، اندازه نصب برای «کیت توسعه نرم‌افزار Google Maps برای iOS» نسخه ۹.۰ حدود ۱۸ مگابایت است.

توجه: با نسخه ۹.۲.۰، GoogleMapsCore و GoogleMapsBase در GoogleMaps XCFramework ادغام شده‌اند. به راه‌اندازی دیگری نیاز نیست.

کیت توسعه نرم‌افزار Google Maps برای iOS درحال‌حاضر از «کتابخانه‌های ادغام‌پذیر» پشتیبانی نمی‌کند. برای جلوگیری از خرابی‌های پیونددهنده درطول ساخت نسخه پخش، مطمئن شوید که تنظیم Build Mergeable Library در پروژه Xcode شما روی No (پیش‌فرض) تنظیم شده باشد.

Swift Package Manager

کیت توسعه نرم‌افزار Google Maps برای iOS را می‌توان ازطریق Swift Package Manager نصب کرد. برای افزودن کیت توسعه نرم‌افزار، مطمئن شوید که همه وابستگی‌های موجود کیت توسعه نرم‌افزار Maps برای iOS را برداشته‌اید.

برای افزودن SDK به پروژه جدید یا موجود، این مراحل را دنبال کنید:

1. ‫Xcode project یا workspace را باز کنید، سپس به File > Add Package Dependencies بروید.
2. https://github.com/googlemaps/ios-maps-sdk را به‌عنوان نشانی وب وارد کنید، Enter را فشار دهید تا بسته را وارد کنید، و روی «افزودن بسته» کلیک کنید.
3. برای نصب version خاص، فیلد قانون وابستگی را روی یکی از گزینه‌های مبتنی بر نسخه تنظیم کنید. برای پروژه‌های جدید، توصیه می‌کنیم جدیدترین نسخه را مشخص کنید و از گزینه «نسخه دقیق» استفاده کنید. پس‌از تکمیل، روی «افزودن بسته» کلیک کنید.
4. در پنجره انتخاب محصولات بسته، تأیید کنید که GoogleMaps (برای نسخه‌های قدیمی‌تر از ۹.۰.۰، تأیید کنید که GoogleMaps، GoogleMapsBase، و GoogleMapsCore) به هدف main تعیین‌شده شما اضافه خواهد شد. پس‌از تکمیل، روی «افزودن بسته» کلیک کنید.
5. برای درستی‌سنجی نصب، به قاب General (عمومی) هدف بروید. در Frameworks, Libraries, and Embedded Content باید بسته‌های نصب‌شده را ببینید. همچنین می‌توانید بخش «وابستگی‌های بسته» را در «Project Navigator» مشاهده کنید تا بسته و نسخه آن را تأیید کنید.

برای به‌روزرسانی package برای پروژه موجود، این مراحل را دنبال کنید:

1. اگر از نسخه‌ای قدیمی‌تر از ۹.۰.۰ ارتقا می‌دهید، باید وابستگی‌های زیر را پس‌از ارتقا دادن بردارید: GoogleMapsBase، GoogleMapsCore، و GoogleMapsM4B. وابستگی را برای GoogleMaps برندارید. برای اطلاعات بیشتر، یادداشت‌های انتشار نسخه ۹.۰.۰ را ببینید.

   از تنظیمات پیکربندی پروژه Xcode، چارچوب‌ها، کتابخانه‌ها، و محتوای جاسازی‌شده را پیدا کنید. از علامت منفی(-) برای برداشتن چارچوب زیر استفاده کنید:

   • GoogleMapsBase (فقط برای ارتقا از نسخه‌های قدیمی‌تر از ۹.۰.۰)
   • GoogleMapsCore (فقط برای ارتقا از نسخه‌های قدیمی‌تر از ۹.۰.۰)
   • GoogleMapsM4B (فقط برای ارتقا از نسخه‌های قدیمی‌تر از ۹.۰.۰)
2. از Xcode، به فایل > بسته‌ها > به‌روزرسانی به جدیدترین نسخه‌های بسته بروید.
3. برای درستی‌سنجی نصب، به بخش وابستگی‌های بسته در Project Navigator بروید تا بسته و نسخه آن را درستی‌سنجی کنید.

مهم: گاهی اوقات، مصنوعات حل نمی‌شوند یا ممکن است خطاهایی رخ دهد، در این صورت «File > Packages > Reset Package Cache» (فایل > بسته‌ها> بازنشانی حافظه نهان بسته) را انتخاب کنید.

برای برداشتن وابستگی‌های موجود «کیت توسعه نرم‌افزار Maps برای iOS» که بااستفاده از CocoaPods اضافه شده‌اند، این مراحل را دنبال کنید:

1. فضای کاری Xcode را ببندید. پایانه را باز کنید و فرمان زیر را اجرا کنید:

   sudo gem install cocoapods-deintegrate cocoapods-clean
   pod deintegrate
   pod cache clean --all

2. Podfile، Podfile.resolved، و Xcode workspace را بردارید اگر از آن‌ها برای چیزی غیراز CocoaPods استفاده نمی‌کنید.

برای برداشتن کیت توسعه نرم‌افزار Google Maps موجود برای iOS که به‌صورت دستی نصب شده است، این مراحل را دنبال کنید:

1. از تنظیمات پیکربندی پروژه Xcode، چارچوب‌ها، کتابخانه‌ها، و محتوای جاسازی‌شده را پیدا کنید. از علامت منفی (-) برای برداشتن چارچوب زیر استفاده کنید:
   • GoogleMaps
   • GoogleMapsBase (فقط برای نصب‌های قدیمی‌تر از نسخه ۹.۲.۰)
   • GoogleMapsCore (فقط برای نصب‌های قدیمی‌تر از نسخه ۹.۲.۰)
   • GoogleMapsM4B (فقط برای نصب‌های قدیمی‌تر از نسخه ۹.۰.۰)
2. از فهرست راهنمای سطح بالای پروژه Xcode، بسته GoogleMaps را بردارید.

نصب دستی

این راهنما نحوه افزودن دستی XCFrameworks حاوی «کیت توسعه نرم‌افزار Maps برای iOS» به پروژه‌تان و پیکربندی تنظیمات ساخت در Xcode را شرح می‌دهد. XCFramework یک بسته دودویی است که در چندین پلاتفرم ازجمله دستگاه‌هایی که از Apple silicon استفاده می‌کنند، استفاده می‌شود.

1. فایل‌های منبع و دودویی کیت توسعه نرم‌افزار زیر را بارگیری کنید:
   • GoogleMaps
   • GoogleMapsResources
2. فایل‌ها را استخراج کنید تا به XCFrameworks و منابع دسترسی پیدا کنید.
3. اگر هنوز پروژه Xcode ندارید، همین‌حالا پروژه‌ای ایجاد کنید و آن را در دستگاه محلی‌تان ذخیره کنید. اگر در توسعه iOS تازه‌کار هستید:
   1. پروژه جدیدی ایجاد کنید.
   2. الگوی iOS > برنامه را انتخاب کنید.
   3. در صفحه گزینه‌های پروژه:
      1. نام پروژه را وارد کنید.
      2. مقدار فیلد شناسه بسته نرم‌افزاری را ثبت کنید. می‌توانید از آن مقدار برای محدود کردن کلید میانای API خود در زیر استفاده کنید.
      3. میانای پروژه را روی داستان‌نما تنظیم کنید.
      4. زبان را روی Swift یا Objective-C تنظیم کنید.
4. برگه عمومی را باز کنید. XCFrameworks زیر را به پروژه خود در بخش Frameworks, Libraries, and Embedded Content بکشید. مطمئن شوید جاسازی نشود را انتخاب کنید:
   • GoogleMaps.xcframework
5. GoogleMaps.bundle را از GoogleMapsResources که بارگیری کرده‌اید در دایرکتوری سطح بالای پروژه Xcode خود کپی کنید. حتماً کپی کردن موارد در پوشه گروه مقصد را هنگام درخواست انتخاب کنید.
6. پروژه‌تان را از Project Navigator انتخاب کنید و هدف برنامه‌تان را انتخاب کنید.
7. برگه Build Phases را برای هدف برنامه‌تان باز کنید. در پیوند دادن دودویی با کتابخانه‌ها، چارچوب‌ها و کتابخانه‌های زیر را اضافه کنید:
   • Accelerate.framework
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • MetricKit.framework
   • OpenGLES.framework (فقط اگر از OpenGL استفاده می‌کنید)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. پروژه‌تان را به‌جای هدف خاصی انتخاب کنید و برگه تنظیمات ساخت را باز کنید. در بخش Linking - General -> Other Linker Flags، -ObjC را به «Debug» و «Release» اضافه کنید. اگر این تنظیمات قابل‌مشاهده نیست، فیلتر را در نوار تنظیمات ساخت از پایه به همه تغییر دهید.

9. برای نصب کیت توسعه نرم‌افزار مکان‌ها برای iOS XCFramework، شروع به کار با کیت توسعه نرم‌افزار مکان‌ها برای iOS را ببینید.

مرحله ۳: کلید میانای API را به پروژه اضافه کنید

در دریافت کلید میانای API، کلید میانای API برای برنامه‌تان تولید کردید. اکنون آن کلید را به پروژه Xcode خود اضافه کنید.

در مثال‌های زیر، YOUR_API_KEY را با کلید میانای API خودتان جایگزین کنید.

توجه: اگر شناسه بسته نرم‌افزاری پروژه‌تان را ثبت کرده‌اید یا آن را از مشخصه‌های پروژه دریافت کرده‌اید، از آن برای محدود کردن کلید میانای API خود استفاده کنید تا فقط با برنامه‌های iOS دارای آن شناسه بسته نرم‌افزاری خاص استفاده شود. برای اطلاعات بیشتر، محدود کردن کلیدهای API را ببینید.

Swift

کلید میانای برنامه‌سازی کاربردی خود را به‌صورت زیر به AppDelegate.swift اضافه کنید:

1. عبارت وارد کردن زیر را اضافه کنید:

   import GoogleMaps

2. بااستفاده از کلید میانای برنامه‌سازی کاربردی، موارد زیر را به روش application(_:didFinishLaunchingWithOptions:) اضافه کنید:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. اگر از Places API هم استفاده می‌کنید، کلیدتان را دوباره همان‌طور که در اینجا نشان داده شده است اضافه کنید:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

آبجکتیو-سی

کلید میانای برنامه‌سازی کاربردی خود را به‌صورت زیر به AppDelegate.m اضافه کنید:

1. عبارت وارد کردن زیر را اضافه کنید:

   @import GoogleMaps;

2. بااستفاده از کلید میانای برنامه‌سازی کاربردی، موارد زیر را به روش application:didFinishLaunchingWithOptions: اضافه کنید:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. اگر از Places API هم استفاده می‌کنید، کلیدتان را دوباره همان‌طور که در اینجا نشان داده شده است اضافه کنید:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

مرحله ۴ (اختیاری): بررسی فایل «مانیفست حریم خصوصی Apple»

توجه: موارد زیر زمانی مربوط است که برنامه‌تان را در فروشگاه وب مستقر می‌کنید.

Apple جزئیات حریم خصوصی برنامه را برای برنامه‌های موجود در App Store الزامی کرده است. برای اطلاع از به‌روزرسانی‌ها و اطلاعات بیشتر، به صفحه جزئیات حریم خصوصی Apple App Store مراجعه کنید.

فایل «مانیفست حریم خصوصی Apple» در دسته منابع کیت توسعه نرم‌افزار گنجانده شده است. برای تأیید اینکه «فایل مانیفست حریم خصوصی» اضافه شده است و برای بررسی محتوای آن، بایگانی‌ای از برنامه‌تان ایجاد کنید و از بایگانی گزارش حریم خصوصی تولید کنید.

مرحله ۵ (اختیاری): طرح‌واره‌های نشانی وب مورداستفاده میانای برنامه‌سازی کاربردی را اعلام کنید

از iOS 9 و Xcode 7، برنامه‌ها طرح‌واره‌های نشانی وب را که قصد دارند باز کنند با مشخص کردن طرح‌واره‌ها در فایل Info.plist برنامه اعلام می‌کنند. وقتی کاربر روی نشان‌واره Google در نقشه کلیک می‌کند، «کیت توسعه نرم‌افزار Google Maps برای iOS» برنامه تلفن همراه Google Maps را باز می‌کند و بنابراین برنامه شما می‌تواند طرح‌واره‌های نشانی وب مربوطه را اعلام کند.

برای اعلام طرح‌واره‌های نشانی وب استفاده‌شده توسط کیت توسعه نرم‌افزار Google Maps برای iOS، خطوط زیر را به Info.plist خود اضافه کنید:

 <key>LSApplicationQueriesSchemes</key>
 <array>
        <string>googlechromes</string>
        <string>comgooglemaps</string>
    </array>

تصویر زیر پیکربندی را در واسط کاربر Xcode نشان می‌دهد:

بدون اعلامیه بالا، وقتی کاربر روی نشان‌واره Google در نقشه تک‌ضرب می‌زند، ممکن است خطاهای زیر رخ دهد:

• -canOpenURL: failed for URL: "comgooglemaps://" - error: "This app is not allowed to query for scheme comgooglemaps"
• -canOpenURL: failed for URL: "googlechromes://" - error: "This app is not allowed to query for scheme googlechromes"

برای حذف این خطاها، اظهارنامه را به Info.plist خود اضافه کنید.

قدم بعدی چیست

اکنون که کلید میانای API و پروژه Xcode دارید، برنامه‌ها را ایجاد و اجرا کنید. کیت توسعه نرم‌افزار پیمایش برای iOS آموزش‌های گام‌به‌گام و برنامه‌های نمونه زیادی ارائه می‌دهد که به شما کمک می‌کند شروع کنید. برای جزئیات بیشتر، به اینجا مراجعه کنید:

• افزودن نقشه با نشانگر.
• انتخاب مکان فعلی و نمایش جزئیات روی نقشه.
• زمین‌کدیابی معکوس.
• نمونه‌های کد و codelabs دردسترس را بررسی کنید.
• برای راهکارهای سرتاسری، راهکارهای Maps موجود را مرور کنید.