إعداد مشروع Xcode

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

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

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

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

  • Xcode الإصدار 14.0 أو إصدار أحدث
  • كاكاوبود

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

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

استخدام CocoaPods

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

إذا لم تكن أداة 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. في ما يلي مثال يتضمن التبعية التي تحتاجها لحزمة تطوير البرامج (SDK) لـ "خرائط Google" لنظام التشغيل iOS:
    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '14.0'
    
    target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
      pod 'GoogleMaps', '8.3.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) وملفات الموارد التالية:
  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
    • (لعملاء الخطة المميّزة فقط) GoogleMapsM4B.xcframework
  5. اسحب GoogleMaps.bundle من GoogleMapsResources الذي نزّلته إلى دليل المستوى الأعلى لمشروع Xcode. تأكّد من اختيار نسخ العناصر عند الحاجة عندما يُطلب منك ذلك.
  6. اختَر مشروعك من Project Navigator (أداة مستكشف المشروعات)، واختَر هدف تطبيقك.
  7. افتح علامة التبويب مراحل الإنشاء لهدف تطبيقك، وضمن ربط النظام الثنائي بالمكتبات، وأضِف أُطر العمل والمكتبات التالية:
    • Accelerate.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. اختَر مشروعك بدلاً من استهدافه، وافتح علامة التبويب Build Settings (إعدادات الإصدار). في القسم علامات رابط أخرى، أضِف -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. إذا كنت تستخدم أيضًا واجهة برمجة تطبيقات الأماكن، أضِف المفتاح مرة أخرى على النحو الموضّح هنا:
    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

  1. أضف عبارة الاستيراد التالية:
    @import GoogleMaps;
  2. أضِف ما يلي إلى طريقة application:didFinishLaunchingWithOptions: باستخدام مفتاح واجهة برمجة التطبيقات:
    [GMSServices provideAPIKey:@"YOUR_API_KEY"];
  3. إذا كنت تستخدم أيضًا واجهة برمجة تطبيقات الأماكن، أضِف المفتاح مرة أخرى على النحو الموضّح هنا:
    [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 الخاص بالتطبيق. تفتح حزمة SDK للخرائط لنظام التشغيل iOS تطبيق خرائط Google للجوّال عندما ينقر المستخدم على شعار Google على الخريطة، وبالتالي يمكن لتطبيقك توضيح أنظمة عناوين URL ذات الصلة.

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

LSApplicationQueriesSchemes googlechromes comgooglemaps

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

إعداد LSApplicationQuerySchemes في Xcode

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

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

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

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

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