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

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

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

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

برای ساختن پروژه بااستفاده از «کیت توسعه نرم‌افزار Google Maps برای iOS»، موارد زیر را بارگیری و نصب کنید:

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

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

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

Swift Package Manager

کیت توسعه نرم‌افزار 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، Frameworks, Libraries, and Embedded Content را پیدا کنید. از علامت منها(-) برای برداشتن چارچوب زیر استفاده کنید:

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

برای برداشتن وابستگی‌های موجود «کیت توسعه نرم‌افزار 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 SDK for iOS به پروژه‌تان و پیکربندی تنظیمات ساخت در Xcode را شرح می‌دهد. ‫XCFramework یک بسته دودویی است که در چندین پلاتفرم استفاده می‌کنید، ازجمله دستگاه‌هایی که از Apple silicon استفاده می‌کنند.

  1. فایل‌های منبع و دودویی کیت توسعه نرم‌افزار زیر را بارگیری کنید:
  2. فایل‌ها را از حالت فشرده خارج کنید تا به XCFrameworks و منابع دسترسی پیدا کنید.
  3. اگر هنوز پروژه Xcode ندارید، اکنون پروژه‌ای ایجاد کنید و آن را در دستگاه محلی‌تان ذخیره کنید. اگر در توسعه iOS تازه‌کار هستید:
    1. پروژه جدیدی ایجاد کنید.
    2. الگوی iOS > برنامه را انتخاب کنید.
    3. در صفحه گزینه‌های پروژه:
      1. نام پروژه را وارد کنید.
      2. مقدار فیلد شناسه دسته نرم‌افزاری را ثبت کنید. می‌توانید از آن مقدار برای محدود کردن کلید میانای API خود در زیر استفاده کنید.
      3. میانای پروژه را روی داستان‌نما تنظیم کنید.
      4. زبان را روی Swift یا Objective-C تنظیم کنید.
  4. برگه موارد کلی را باز کنید. XCFrameworks زیر را به پروژه خود در بخش چارچوب‌ها، کتابخانه‌ها، و محتوای جاسازی‌شده بکشید. حتماً جاسازی نشود را انتخاب کنید:
    • GoogleMaps.xcframework
  5. GoogleMaps.bundle را از GoogleMapsResources که بارگیری کرده‌اید در دایرکتوری سطح بالای پروژه Xcode خود کپی کنید. هنگام درخواست، حتماً کپی کردن موارد در پوشه گروه مقصد را انتخاب کنید.
  6. پروژه‌تان را از Project Navigator انتخاب کنید و هدف برنامه‌تان را انتخاب کنید.
  7. برگه Build Phases را برای هدف برنامه‌تان باز کنید. در Link Binary with Libraries، چارچوب‌ها و کتابخانه‌های زیر را اضافه کنید:
    • 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. برای نصب Places SDK برای iOS XCFramework، به شروع به کار با Places SDK برای iOS مراجعه کنید.

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

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

در مثال‌های زیر، YOUR_API_KEY را با کلید میانای 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 نشان می‌دهد:

پیکربندی `LSApplicationQueriesSchemes` در 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 آموزش‌های گام‌به‌گام و برنامه‌های نمونه زیادی ارائه می‌دهد که به شما کمک می‌کند شروع کنید. برای جزئیات بیشتر، به این مقاله مراجعه کنید: