إعداد مشروع Xcode

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

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

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

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

  • الإصدار 14.0 من Xcode أو إصدار أحدث

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

مدير حِزم Swift

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

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

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

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

  1. من Xcode، انتقل إلى "ملف > الحزم > التحديث إلى أحدث إصدارات الحزمة".
  2. للتحقّق من التثبيت، انتقِل إلى قسم تبعيات الحزمة في 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، ابحث عن Frameworks والمكتبات والمحتوى المضمَّن. استخدِم علامة الطرح(-) لإزالة إطار العمل التالي:
    • GoogleMaps.xcframework
    • GoogleMapsBase.xcframework
    • GoogleMapsCore.xcframework
  2. يجب إزالة حزمة GoogleMaps من دليل المستوى الأعلى لمشروع Xcode.

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. اضبط واجهة المشروع على Storyboard (لوحة القصة).
      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 يدويًا إلى مشروعك وتهيئة إعدادات الإصدار في Xcode. XCFramework عبارة عن حزمة ثنائية يمكنك استخدامها على أنظمة أساسية متعددة، بما في ذلك الأجهزة التي تستخدم Apple silicon.
  1. نزِّل برامج SDK الثنائية وملفات الموارد التالية:
  2. قم بفك ضغط الملفات المضغوطة للوصول إلى XCFrameworks والموارد.
  3. إذا لم يكن لديك مشروع Xcode حتى الآن، يمكنك إنشاء مشروع الآن وحفظه على جهازك المحلي. إذا كنت مبتدئًا في مجال تطوير تطبيقات iOS:
    1. أنشِئ مشروعًا جديدًا.
    2. اختَر نموذج iOS > التطبيق.
    3. في شاشة خيارات المشروع:
      1. أدخِل اسم المشروع.
      2. سجِّل قيمة حقل معرِّف الحزمة. ويمكنك استخدام هذه القيمة لتقييد مفتاح واجهة برمجة التطبيقات أدناه.
      3. اضبط واجهة المشروع على Storyboard (لوحة القصة).
      4. اضبط اللغة على Swift أو Objective-C.
  4. افتح علامة التبويب الإعدادات العامة. اسحب عناصر XCFrameworks التالية إلى مشروعك ضِمن Frameworks, Libraries and inline content (أعمال الأطر والمكتبات والمحتوى المضمَّن). تأكَّد من اختيار عدم التضمين لكل 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
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework
  8. اختَر مشروعك بدلاً من هدف محدّد، وافتح علامة التبويب إعدادات الإنشاء. في القسم Linking - General (الربط - عام -> آخر علامة روابط أخرى)، أضِف -ObjC إلى "تصحيح الأخطاء" و "الإصدار". إذا لم تكن هذه الإعدادات مرئية، عليك تغيير الفلتر في شريط إعدادات الإنشاء من أساسي إلى الكل.

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

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

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

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

.

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

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"];

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

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 الخاص بالتطبيق. تفتح حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS تطبيق خرائط Google للجوّال عندما ينقر المستخدم على شعار Google على الخريطة، وبالتالي يمكن لتطبيقك الإعلان عن مخططات عناوين URL ذات الصلة.

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

LSApplicationQueriesSchemes googlechromes خرائط Google

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

إعداد LSApplicationQuerySchemes في
Xcode

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

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

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

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

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