إعداد مشروع Flutter

Android

اضبط الحدّ الأدنى لإصدار حزمة تطوير البرامج (SDK) لنظام التشغيل Android.

1. افتح ملف الإعداد android/app/build.gradle في بيئة التطوير المتكاملة (IDE) المفضّلة لديك.
2. غيِّر قيمة android.defaultConfig.minSdkVersion إلى 21:

     android {
       //...
       defaultConfig {
           applicationId "com.example.google_maps_in_flutter"
           minSdkVersion 21     // Set to 21
           targetSdkVersion flutter.targetSdkVersion
           versionCode flutterVersionCode.toInteger()
           versionName flutterVersionName
       }
       //...
     }

3. عند ضبط إعدادات defaultConfig، حدِّد ApplicationID الفريد الخاص بك.
4. مزامنة تغييرات مشروعك مع Gradle

iOS

اضبط الحدّ الأدنى لإصدار نظام التشغيل iOS.

1. افتح ملف الإعداد ios/Podfile في بيئة التطوير المتكاملة (IDE) المفضّلة لديك.
2. أضِف الأسطر التالية إلى بداية ملف Podfile:

     # Set platform to 14.0 to enable latest Google Maps SDK
     platform :ios, '14.0'

Android

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secrets Gradle لأجهزة Android.

لتثبيت المكوّن الإضافي Secrets Gradle لأجهزة Android وتخزين مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

1. في "استوديو Android"، افتح ملف build.gradle.kts أو build.gradle ذي المستوى الأعلى وأضِف الرمز التالي إلى كتلة plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وأضِف الرمز التالي إلى العنصر plugins.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. إذا كنت تستخدم "استوديو Android"، زامن مشروعك مع Gradle.
4. افتح ملف secrets.properties في الدليل ذي المستوى الأعلى، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك. احرص على إضافة secrets.properties إلى ملف .gitignore (أو استبعاده من نظام التحكّم في الإصدارات) حتى لا يتم إدراج مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدارات.

   MAPS_API_KEY=YOUR_API_KEY

5. أنشئ ملف local.defaults.properties في الدليل ذي المستوى الأعلى، وهو المجلد نفسه الذي يحتوي على ملف secrets.properties، ثم أضِف الرمز التالي.

   MAPS_API_KEY=DEFAULT_API_KEY

   الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على ملف secrets.properties حتى لا تفشل عمليات الإنشاء. قد يحدث ذلك إذا نسخت التطبيق من نظام تحكّم في الإصدارات يحذف secrets.properties ولم تنشئ بعد ملف secrets.properties على جهازك لتقديم مفتاح واجهة برمجة التطبيقات.

6. في ملف AndroidManifest.xml، انتقِل إلى com.google.android.geo.API_KEY وعدِّل السمة android:value على النحو التالي:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   ملاحظة: ‫com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على واجهات برمجة تطبيقات متعددة مستندة إلى "خرائط Google" على نظام Android الأساسي، بما في ذلك حزمة تطوير البرامج (SDK) لتطبيق Flutter. لضمان التوافق مع الأنظمة القديمة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. في حال تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

7. في استوديو Android، افتح ملف build.gradle.kts أو build.gradle على مستوى الوحدة وعدِّل السمة secrets. إذا لم تكن السمة secrets متوفّرة، أضِفها.

   عدِّل سمات المكوّن الإضافي لضبط propertiesFileName على "secrets.properties"، واضبط defaultPropertiesFileName على "local.defaults.properties"، واضبط أي سمات أخرى.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

ملاحظة: كما هو موضّح أعلاه، com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على عدة واجهات برمجة تطبيقات مستندة إلى "خرائط Google" على نظام Android الأساسي، بما في ذلك حزمة تطوير البرامج (SDK) في Flutter. لضمان التوافق مع الأنظمة القديمة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن لأي تطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

iOS

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

1. افتح ملف ios/Runner/AppDelegate.swift في مشروع Flutter باستخدام بيئة التطوير المتكاملة (IDE) المفضّلة لديك.
2. أضِف عبارة الاستيراد التالية لإضافة حزمة "خرائط Google" لتطبيق Flutter إلى تطبيقك:

import GoogleMaps

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

   GMSServices.provideAPIKey("YOUR_API_KEY")

4. احفظ ملف AppDelegate.swift وأغلِقه.

يجب أن يشبه ملف AppDelegate.swift المكتمل ما يلي:

import UIKit
import Flutter
import GoogleMaps  // Add this import

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)

    // TODO: Add your Google Maps API key
    GMSServices.provideAPIKey("YOUR_API_KEY")

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

الويب

أضِف مفتاح واجهة برمجة التطبيقات إلى ملف تطبيق index.html.

1. افتح ملف web/index.html في مشروع Flutter باستخدام بيئة التطوير المتكاملة (IDE) المفضّلة لديك.
2. أضِف علامة النص البرمجي التالية داخل العلامة <head>، مع استبدال مفتاح واجهة برمجة التطبيقات بـ YOUR_API_KEY.

   <script>
     (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
       key: "YOUR_API_KEY",
       v: "weekly",
       // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
       // Add other bootstrap parameters as needed, using camel case.
     });
   </script>

3. احفظ ملف index.html وأغلقه.

   يجب أن يشبه قسم head الكامل في index.html ما يلي:

       <head>
         <base href="/">
         
         <meta charset="UTF-8">
         <meta content="IE=Edge" http-equiv="X-UA-Compatible">
         <meta name="description" content="A new Flutter project.">
         
         <!-- iOS meta tags & icons -->
         <meta name="apple-mobile-web-app-capable" content="yes">
         <meta name="apple-mobile-web-app-status-bar-style" content="black">
         <meta name="apple-mobile-web-app-title" content="google_maps_in_flutter">
         <link rel="apple-touch-icon" href="icons/Icon-192.png">
         
         <script>
           (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
             key: "YOUR_API_KEY",
             v: "weekly",
             // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
             // Add other bootstrap parameters as needed, using camel case.
             });
         </script>
         
         <title>google_maps_in_flutter</title>
         <link rel="manifest" href="manifest.json">
       </head>