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

مدیر بسته سوئیفت

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

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

1. project یا workspace Xcode خود را باز کنید، سپس به File > Add Package Dependencies بروید.
2. آدرس https://github.com/googlemaps/ios-maps-sdk را به عنوان URL وارد کنید، برای دریافت بسته، Enter را فشار دهید و روی «افزودن بسته» کلیک کنید.
3. برای نصب یک version خاص، فیلد Dependency Rule را روی یکی از گزینه‌های مبتنی بر نسخه تنظیم کنید. برای پروژه‌های جدید، توصیه می‌کنیم آخرین نسخه را مشخص کرده و از گزینه "Exact Version" استفاده کنید. پس از تکمیل، روی "Add Package" کلیک کنید.

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

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

   از تنظیمات پیکربندی پروژه Xcode خود، Frameworks، Libraries و Embedded Content را پیدا کنید. از علامت منها (-) برای حذف framework زیر استفاده کنید:

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

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

1. فضای کاری Xcode خود را ببندید. ترمینال را باز کنید و دستور زیر را اجرا کنید:

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

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

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

نصب دستی

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

1. فایل‌های باینری و منابع SDK زیر را دانلود کنید:
   • گوگل مپ
   • منابع گوگل مپ
2. برای دسترسی به XCFrameworks و منابع، فایل‌ها را استخراج کنید.
3. اگر هنوز پروژه Xcode ندارید، همین حالا یکی ایجاد کنید و آن را در دستگاه محلی خود ذخیره کنید. اگر در توسعه iOS تازه‌کار هستید:
   1. یک پروژه جدید ایجاد کنید.
   2. قالب iOS > App را انتخاب کنید.
   3. در صفحه گزینه‌های پروژه:
      1. نام پروژه را وارد کنید.
      2. مقدار فیلد شناسه بسته (Bundle identifier) ​​را ثبت کنید. می‌توانید از آن مقدار برای محدود کردن کلید API خود در زیر استفاده کنید.
      3. رابط پروژه را روی Storyboard تنظیم کنید.
      4. زبان را روی Swift یا Objective-C تنظیم کنید.
4. برگه عمومی ( General ) را باز کنید. XCFrameworks زیر را در قسمت چارچوب‌ها (Frameworks)، کتابخانه‌ها (Libraries) و محتوای جاسازی‌شده (Embedded Content) به پروژه خود بکشید (drag) و رها کنید. مطمئن شوید که گزینه «عدم جاسازی» (Do Not Embed) را انتخاب کرده‌اید:
   • GoogleMaps.xcframework
5. GoogleMaps.bundle را از GoogleMapsResources که دانلود کرده‌اید، در دایرکتوری سطح بالای پروژه Xcode خود کپی کنید. هنگام درخواست، حتماً گزینه Copy items into destination group’s folder را انتخاب کنید.
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" اضافه کنید. اگر این تنظیمات قابل مشاهده نیستند، فیلتر را در نوار تنظیمات ساخت از Basic به All تغییر دهید.

9. برای نصب Places SDK برای iOS XCFramework، به بخش «شروع به کار با Places SDK برای iOS» مراجعه کنید.

کوکوپادز

کیت توسعه نرم‌افزار نقشه‌ها برای iOS به عنوان یک پاد CocoaPods در دسترس است. CocoaPods یک ابزار مدیریت وابستگی متن‌باز برای پروژه‌های Swift و Objective-C Cocoa است.

اگر ابزار CocoaPods را از قبل ندارید، با اجرای دستور زیر از ترمینال، آن را روی macOS نصب کنید. برای جزئیات بیشتر، به راهنمای شروع به کار با CocoaPods مراجعه کنید.

sudo gem install cocoapods

یک Podfile برای Maps SDK برای iOS ایجاد کنید و از آن برای نصب API و وابستگی‌های آن استفاده کنید:

1. اگر هنوز پروژه Xcode ندارید، همین حالا یکی ایجاد کنید و آن را در دستگاه محلی خود ذخیره کنید. اگر در توسعه iOS تازه‌کار هستید:
   1. یک پروژه جدید ایجاد کنید.
   2. قالب iOS > App را انتخاب کنید.
   3. در صفحه گزینه‌های پروژه:
      1. نام پروژه را وارد کنید.
      2. مقدار فیلد شناسه بسته (Bundle identifier) ​​را ثبت کنید. می‌توانید از آن مقدار برای محدود کردن کلید API خود در زیر استفاده کنید.
      3. رابط پروژه را روی Storyboard تنظیم کنید.
      4. زبان را روی Swift یا Objective-C تنظیم کنید.
2. فایلی با نام Podfile در دایرکتوری پروژه خود ایجاد کنید. این فایل وابستگی‌های پروژه شما را تعریف می‌کند.
3. Podfile را ویرایش کنید و وابستگی‌های خود را به همراه نسخه‌های آنها اضافه کنید. در اینجا مثالی آورده شده است که شامل وابستگی مورد نیاز برای Maps SDK برای iOS است:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '10.4.0'
   end

   مرتباً pod outdated را اجرا کنید تا زمان انتشار نسخه جدیدتر را تشخیص دهد و مطمئن شوید که همیشه از آخرین نسخه استفاده می‌کنید. در صورت لزوم، به آخرین نسخه ارتقا دهید .
4. Podfile را ذخیره کنید.

5. یک ترمینال باز کنید و به دایرکتوری حاوی Podfile بروید:

   cd <path-to-project>

6. دستور pod install را اجرا کنید. این دستور API های مشخص شده در Podfile را به همراه هرگونه وابستگی که ممکن است داشته باشند، نصب خواهد کرد.

   pod install

7. Xcode را ببندید و سپس فایل .xcworkspace پروژه خود را باز کنید (روی آن دوبار کلیک کنید). از این به بعد، برای باز کردن پروژه باید از فایل .xcworkspace استفاده کنید.

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

1. یک ترمینال باز کنید و به دایرکتوری پروژه حاوی Podfile بروید.
2. دستور pod update را اجرا کنید. این دستور تمام API های مشخص شده در Podfile را به آخرین نسخه به روز می کند.

سویفت

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

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

   import GoogleMaps

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

   GMSServices.provideAPIKey("YOUR_API_KEY")

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

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

هدف-سی

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

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

   @import GoogleMaps;

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

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

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

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];