إعداد مشروع Xcode

بعد تمكين الفوترة وإنشاء مفتاح واجهة برمجة التطبيقات، تكون جاهزًا لإعداد مشروع Xcode الذي تستخدمه لتطوير تطبيقك.

تتوفر ملاحظات الإصدار لكل إصدار.

الخطوة 1: تثبيت البرنامج المطلوب

لإنشاء مشروع باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS، يجب تنزيل وتثبيت:

• Xcode الإصدار 15.0 أو إصدار أحدث

الخطوة 2: إنشاء مشروع Xcode وتثبيت "حزمة تطوير البرامج (SDK) للخرائط" لنظام التشغيل iOS

مدير حزم Swift

يمكن تثبيت حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS عبر أداة إدارة الحزم Swift. لإضافة حزمة تطوير البرامج (SDK)، تأكّد من إزالة أيّ حزمة SDK حالية من "خرائط Google" لاعتماديات نظام التشغيل iOS.

ملاحظة مهمة: تفترض هذه التعليمات استخدام Xcode 15 أو إصدار أحدث، ولكن يجب أن تكون هذه التعليمات مماثلة للإصدارات السابقة من Xcode.

لإضافة حزمة تطوير البرامج (SDK) إلى مشروع جديد أو حالي، اتّبِع الخطوات التالية:

1. افتح تطبيق Xcode project أو workspace، ثم انتقِل إلى ملف > إضافة تبعيات الحزمة.
2. أدخِل https://github.com/googlemaps/ios-maps-sdk كعنوان URL، واضغط على Enter لسحب الحزمة، ثم انقر على "إضافة حزمة".
3. لتثبيت علامة version محدّدة، اضبط حقل قاعدة التبعية على أحد الخيارات المستندة إلى الإصدار. بالنسبة إلى المشاريع الجديدة، ننصح بتحديد أحدث إصدار واستخدام خيار "النسخة المحددة". بعد اكتمال عملية النقل، انقر على "إضافة حزمة".
4. من نافذة اختيار منتجات الحزمة، تحقَّق من إضافة GoogleMaps (في الإصدارات الأقدم من 9.0.0، وتحقَّق من GoogleMaps وGoogleMapsBase وGoogleMapsCore) إلى هدف main المحدّد. بعد اكتمال عملية النقل، انقر على "إضافة حزمة".
5. للتحقّق من عملية التثبيت، انتقِل إلى جزء General في استهدافك. من المفترَض أن تظهر الحِزَم المثبَّتة في أُطر العمل والمكتبات والمحتوى المضمَّن. يمكنك أيضًا الاطّلاع على قسم "تبعيات الحِزم" ضمن Project Navigator (أداة التنقّل في المشروع) للتحقّق من الحزمة وإصدارها.

لتعديل package لمشروع حالي، اتّبِع الخطوات التالية:

1. في حال الترقية من إصدار أقدم من 9.0.0، عليك إزالة الاعتماديات التالية: GoogleMapsBase وGoogleMapsCore وGoogleMapsM4B بعد الترقية. يجب عدم إزالة تبعية GoogleMaps. لمعرفة مزيد من المعلومات، يمكنك الاطّلاع على ملاحظات الإصدار 9.0.0.

   من إعدادات ضبط مشروع Xcode، ابحث عن الإطارات والمكتبات والمحتوى المضمَّن. استخدِم علامة الطرح(-) لإزالة إطار العمل التالي:

   • GoogleMapsBase (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
   • GoogleMapsCore (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
   • GoogleMapsM4B (للترقيات من الإصدارات السابقة على 9.0.0 فقط)
2. من Xcode، انتقِل إلى "ملف" > "الحِزم" > "تحديث إلى أحدث إصدارات الحزمة".
3. للتحقّق من عملية التثبيت، انتقِل إلى القسم تبعيات الحزمة في Project Navigator (أداة التنقّل في المشروع) للتحقّق من الحزمة وإصدارها.

ملاحظة مهمّة: قد يتعذّر أحيانًا حلّ العناصر أو قد تحدث أخطاء. في هذه الحالة، اختَر "ملف > الحِزم > إعادة ضبط ذاكرة التخزين المؤقت للحِزم".

لإزالة حزمة تطوير البرامج (SDK) الحالية لخرائط Google لتبعيات iOS التي تمت إضافتها باستخدام CocoaPods، اتّبع الخطوات التالية:

1. أغلِق مساحة عمل Xcode. افتح المحطة الطرفية ونفِّذ الأمر التالي:

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

2. أزِل Podfile وPodfile.resolved ورمز Xcode workspace إذا كنت لا تستخدمهما لأي غرض آخر غير CocoaPods.

لإزالة حزمة تطوير البرامج (SDK) الحالية لـ "خرائط Google" لتطبيقات iOS والتي تم تثبيتها يدويًا، اتّبِع الخطوات التالية:

1. من إعدادات ضبط مشروع Xcode، ابحث عن الإطارات والمكتبات والمحتوى المضمَّن. استخدِم علامة الطرح(-) لإزالة إطار العمل التالي:
   • GoogleMaps
   • GoogleMapsBase (فقط لعمليات التثبيت التي تسبق الإصدار 9.0.0)
   • GoogleMapsCore (فقط لعمليات التثبيت التي تسبق الإصدار 9.0.0)
   • GoogleMapsM4B (فقط لعمليات التثبيت التي تسبق الإصدار 9.0.0)
2. من دليل المستوى الأعلى لمشروع Xcode، أزِل الحزمة GoogleMaps.

CocoaPods

تتوفر حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS على شكل مجموعة CocoaPods. CocoaPods هو مدير تبعية مفتوح المصدر لمشاريع Swift وObjective-C Cocoa.

إذا لم تكن لديك أداة CocoaPods، يمكنك تثبيتها على نظام التشغيل macOS من خلال تنفيذ الأمر التالي من الوحدة الطرفية. لمعرفة التفاصيل، يمكنك الاطّلاع على دليل بدء استخدام CocoaPods.

sudo gem install cocoapods

أنشِئ Podfile لحزمة تطوير البرامج (SDK) الخاصة بخرائط Google لنظام التشغيل iOS واستخدِمها لتثبيت واجهة برمجة التطبيقات وتبعياتها:

1. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على جهازك المحلي. إذا كنت مبتدئًا في مجال تطوير تطبيقات iOS:
   1. أنشِئ مشروعًا جديدًا.
   2. اختر نموذج iOS > التطبيق.
   3. على شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على مخطط القصة.
      4. اضبط اللغة على Swift أو Objective-C.
2. أنشئ ملفًا باسم "Podfile" في دليل مشروعك. يحدد هذا الملف تبعيات مشروعك.
3. عدِّل Podfile وأضِف الموارد التابعة لك إلى جانب versions. في ما يلي مثال يتضمن الاعتمادية التي تحتاجها لـ حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS:

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

   احرص على تشغيل pod outdated بانتظام لرصد أي إصدار أحدث لضمان حصولك على أحدث الإصدارات دائمًا. إذا لزم الأمر، يمكنك الترقية إلى أحدث إصدار.
4. احفظ Podfile.

5. افتح نافذة طرفية وانتقِل إلى الدليل الذي يحتوي على Podfile:

   cd <path-to-project>

6. شغِّل الأمر pod install. سيؤدي هذا الإجراء إلى تثبيت واجهات برمجة التطبيقات المحدّدة في Podfile، بالإضافة إلى أي ملحقات قد تكون مرتبطة بها.

   pod install

7. أغلِق Xcode، ثم افتح ملف .xcworkspace الخاص بمشروعك (بالنقر مرّتين) لتشغيل Xcode. ومن الآن فصاعدًا، عليك استخدام ملف .xcworkspace لفتح المشروع.

لتحديث واجهة برمجة التطبيقات لمشروع حالي، اتّبِع الخطوات التالية:

1. افتح نافذة طرفية وانتقِل إلى دليل المشروع الذي يحتوي على Podfile.
2. شغِّل الأمر pod update. سيؤدي هذا الإجراء إلى تحديث جميع واجهات برمجة التطبيقات المحدّدة في Podfile إلى أحدث إصدار.

التثبيت اليدوي

يوضِّح هذا الدليل كيفية إضافة XCFrameworks يدويًا إلى مشروعك في حزمة SDK الخاصة بـ "خرائط Google" لتطبيقات iOS وضبط إعدادات تصميمك في Xcode. XCFramework هو حزمة ثنائية يمكنك استخدامها على عدة أنظمة أساسية، بما في ذلك الأجهزة التي تستخدم Apple silicon.

1. يمكنك تنزيل البرامج الثنائية لحزمة تطوير البرامج (SDK) وملفات الموارد التالية:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsM4B
   • GoogleMapsResources
2. يمكنك استخراج الملفات للوصول إلى XCFrameworks والموارد.
3. إذا لم يكن لديك مشروع Xcode بعد، أنشئ مشروعًا الآن واحفظه على جهازك المحلي. إذا كنت مبتدئًا في مجال تطوير تطبيقات iOS:
   1. أنشِئ مشروعًا جديدًا.
   2. اختر نموذج iOS > التطبيق.
   3. على شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجّل قيمة حقل معرّف الحزمة. يمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على مخطط القصة.
      4. اضبط اللغة على Swift أو Objective-C.
4. افتح علامة التبويب الإعدادات العامة. اسحب عناصر XCFrameworks التالية إلى مشروعك ضمن الإطارات والمكتبات والمحتوى المضمَّن. تأكّد من اختيار عدم التضمين لكل XCFramework:
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
5. انسخ GoogleMaps.bundle من GoogleMapsResources التي نزَّلتها إلى دليل المستوى الأعلى لمشروع Xcode. احرص على اختيار نسخ الملفات إلى مجلد المجموعة الوجهة عندما يُطلب منك ذلك.
6. اختَر مشروعك من Project Navigator، ثم اختَر الهدف الذي يستهدفه تطبيقك.
7. افتح علامة التبويب مراحل التصميم لهدف تطبيقك. ضمن ربط النظام الثنائي بالمكتبات، أضِف أُطر العمل والمكتبات التالية:
   • 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
   • OpenGLES.framework (فقط في حال استخدام OpenGL)
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب إعدادات التصميم. في القسم الربط - عام -> علامات الروابط الأخرى، أضِف -ObjC إلى "تصحيح الأخطاء" و "الإصدار". إذا لم تكن هذه الإعدادات مرئية، غيِّر الفلتر في شريط إعدادات التصميم من أساسي إلى الكل.

9. لتثبيت حزمة تطوير برامج الأماكن لنظام التشغيل iOS XCFramework، يمكنك الاطّلاع على بدء استخدام حزمة تطوير برامج الأماكن لأجهزة iOS.

الخطوة 3: فحص ملف بيان الخصوصية في Apple

تشترط Apple تفاصيل خصوصية التطبيقات للتطبيقات المتوفّرة على App Store. يُرجى الانتقال إلى صفحة تفاصيل خصوصية Apple App Store لمعرفة آخر الأخبار ومزيد من المعلومات.

يتم تضمين ملف بيان الخصوصية من Apple في حزمة الموارد لحزمة تطوير البرامج (SDK). للتأكّد من تضمين "ملف بيان الخصوصية" وفحص محتواه، عليك إنشاء أرشيف لتطبيقك وإنشاء تقرير خصوصية من الأرشيف.

الخطوة 4: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

في القسم الحصول على مفتاح واجهة برمجة تطبيقات، أنشأت مفتاح واجهة برمجة تطبيقات لتطبيقك. ويمكنك الآن إضافة هذا المفتاح إلى مشروع Xcode.

في الأمثلة التالية، استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.

ملاحظة: إذا سجّلت معرّف الحزمة لمشروعك أو حصلت عليه من خصائص المشروع، يمكنك استخدامه لتقييد استخدام مفتاح واجهة برمجة التطبيقات مع تطبيقات iOS التي تستخدم معرّف الحزمة المحدّد فقط. راجِع المقالة تقييد مفاتيح واجهة برمجة التطبيقات

.

لمعرفة المزيد من المعلومات.

Swift

أضِف مفتاح واجهة برمجة التطبيقات إلى AppDelegate.swift على النحو التالي:

1. أضِف عبارة الاستيراد التالية:

   import GoogleMaps

2. أضِف ما يلي إلى طريقة application(_:didFinishLaunchingWithOptions:) باستخدام مفتاح واجهة برمجة التطبيقات:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. إذا كنت تستخدم Places API أيضًا، يمكنك إضافة المفتاح مرة أخرى كما هو موضّح هنا:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

أضِف مفتاح واجهة برمجة التطبيقات إلى AppDelegate.m على النحو التالي:

1. أضِف عبارة الاستيراد التالية:

   @import GoogleMaps;

2. أضِف ما يلي إلى طريقة application:didFinishLaunchingWithOptions: باستخدام مفتاح واجهة برمجة التطبيقات:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. إذا كنت تستخدم Places API أيضًا، يمكنك إضافة المفتاح مرة أخرى كما هو موضّح هنا:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

الخطوة 5: إضافة خريطة

Swift

/*
 *   Copyright 2020 Google Inc. All rights reserved.
 *
 *
 *   Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
 *   file except in compliance with the License. You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software distributed under
 *   the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 *   ANY KIND, either express or implied. See the License for the specific language governing
 *   permissions and limitations under the License.
 */

import UIKit
import GoogleMaps

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        // Create a GMSCameraPosition that tells the map to display the
        // coordinate -33.86,151.20 at zoom level 6.

        let options = GMSMapViewOptions()
        options.camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
        options.frame = self.view.bounds

        let mapView = GMSMapView(options: options)
        self.view.addSubview(mapView)

        // Creates a marker in the center of the map.
        let marker = GMSMarker()
        marker.position = CLLocationCoordinate2D(latitude: -33.86, longitude: 151.20)
        marker.title = "Sydney"
        marker.snippet = "Australia"
        marker.map = mapView
  }
}

Objective-C

/*
*   Copyright 2020 Google Inc. All rights reserved.
*
*
*   Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
*   file except in compliance with the License. You may obtain a copy of the License at
*
*   http://www.apache.org/licenses/LICENSE-2.0
*
*   Unless required by applicable law or agreed to in writing, software distributed under
*   the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
*   ANY KIND, either express or implied. See the License for the specific language governing
*   permissions and limitations under the License.
*/

#import "ViewController.h"
#import <GoogleMaps/GoogleMaps.h>

@interface ViewController()

@end

@implementation ViewController

-   (void)viewDidLoad {
  [super viewDidLoad];
  // Do any additional setup after loading the view.
  // Create a GMSCameraPosition that tells the map to display the
  // coordinate -33.86,151.20 at zoom level 6.
  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
  options.camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:6];
  options.frame = self.view.bounds;
  GMSMapView *mapView = [[GMSMapView alloc] initWithOptions:options];

  [self.view addSubview:mapView];

  // Creates a marker in the center of the map.
  GMSMarker *marker = [[GMSMarker alloc] init];
  marker.position = CLLocationCoordinate2DMake(-33.86, 151.20);
  marker.title = @"Sydney";
  marker.snippet = @"Australia";
  marker.map = mapView;
}

@end

الخطوة 5 (اختيارية): الإفصاح عن مخططات عناوين URL التي تستخدمها واجهة برمجة التطبيقات

بدءًا من نظامَي التشغيل iOS 9 وXcode 7، يمكن للتطبيقات الإفصاح عن مخططات عناوين URL التي تريد فتحها، من خلال تحديد المخططات في ملف Info.plist للتطبيق. وتفتح حزمة "SDK للخرائط" لتطبيقات iOS تطبيق "خرائط Google" المتوافق مع الأجهزة الجوّالة عندما ينقر المستخدم على شعار Google على الخريطة، وبالتالي يمكن لتطبيقك الإفصاح عن مخططات عناوين URL ذات الصلة.

للإشارة إلى مخططات عناوين URL التي تستخدمها "حزمة تطوير البرامج (SDK) للخرائط" لنظام التشغيل iOS، أضِف الأسطر التالية إلى Info.plist:

LSApplicationQueriesSchemes googlechromes خرائط Google

تعرض لقطة الشاشة التالية الإعدادات في واجهة مستخدم Xcode:

بدون البيان أعلاه، يمكن أن تحدث الأخطاء التالية عندما ينقر المستخدم على شعار Google على الخريطة:

• -canOpenURL: أخفق لعنوان URL: "comgooglemaps://" - خطأ: "هذا التطبيق غير مسموح له بطلب البحث عن مخطط comgooglemaps"
• -canOpenURL: تعذّر طلب الزحف إلى عنوان URL: "googlechromes://" - خطأ: "هذا التطبيق غير مسموح له بطلب البحث عن مخطط googlechromes"

لإزالة هذه الأخطاء، أضِف البيان إلى Info.plist.

الخطوات التالية

والآن بعد أن أصبح لديك مفتاح واجهة برمجة التطبيقات ومشروع Xcode، يمكنك إنشاء التطبيقات وتشغيلها. توفر حزمة SDK للتنقل لنظام التشغيل iOS العديد من البرامج التعليمية ونماذج التطبيقات التي يمكن أن تساعدك في البدء. لمزيد من التفاصيل، يُرجى الاطّلاع على:

• عيّنات التعليمات البرمجية
• الفيديوهات التعليمية
  • إضافة خريطة باستخدام محدّد موقع
  • تحديد المكان الحالي وعرض التفاصيل على الخريطة
  • الترميز الجغرافي العكسي
• دروس تطبيقية حول الترميز
• حلول "خرائط Google"