ندعوك للانضمام إلينا في يوم منتدى مطوّري "منصة خرائط Google" القادم في سان فرانسيسكو في ديسمبر. قدِّم طلبك الآن لحضور الفعالية.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إعداد مشروع "استوديو Android"

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

إضافة حزمة تطوير البرامج (SDK) للتنقّل إلى مشروعك

تتوفّر حزمة تطوير البرامج (SDK) للتنقّل من خلال مستودع Google Maven. يمكنك إضافة حزمة تطوير البرامج (SDK) إلى مشروعك باستخدام إعدادات Gradle build.gradle أو Maven pom.xml.

أضِف التبعية التالية إلى إعدادات Gradle أو Maven، مع استبدال العنصر النائب VERSION_NUMBER بالإصدار المطلوب من حزمة تطوير البرامج (SDK) الخاصة بالتنقّل لنظام التشغيل Android.
Gradle
أضِف ما يلي إلى ملف build.gradle على مستوى الوحدة:
dependencies { ... implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER' }
Maven
أضِف ما يلي إلى ملف pom.xml:
<dependencies> ... <dependency> <groupId>com.google.android.libraries.navigation</groupId> <artifactId>navigation</artifactId> <version>VERSION_NUMBER</version> </dependency> </dependencies>
ملاحظة: إذا كنت من عملاء "خدمات التنقّل" الذين يجرون ترقية من مستودع Maven الخاص الأصلي، يُرجى العِلم أنّ أسماء المجموعات والقطع الأثرية قد تغيّرت، ولم يعُد المكوّن الإضافي com.google.cloud.artifactregistry.gradle-plugin ضروريًا.

إذا كانت لديك أي تبعيات تستخدم حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google"، عليك استبعاد التبعية في كل تبعية مُعلَنة تعتمد على حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google".

Gradle

أضِف ما يلي إلى ملف build.gradle ذي المستوى الأعلى:

allprojects {
        ...
        // Required: you must exclude the Google Play service Maps SDK from
        // your transitive dependencies to make sure there won't be
        // multiple copies of Google Maps SDK in your binary, as the Navigation
        // SDK already bundles the Google Maps SDK.
        configurations {
            implementation {
                exclude group: 'com.google.android.gms', module: 'play-services-maps'
            }
        }
}

Maven

أضِف ما يلي إلى ملف pom.xml:

<dependencies>
  <dependency>
  <groupId>project.that.brings.in.maps</groupId>
  <artifactId>MapsConsumer</artifactId>
  <version>1.0</version>
    <exclusions>
      <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
      <exclusion>  <!-- declare the exclusion here -->
        <groupId>com.google.android.gms</groupId>
        <artifactId>play-services-maps</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
</dependencies>

ضبط الإصدار

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

تعديل المواقع المحلية

في مجلد Gradle Scripts، افتح ملف local.properties وأضِف android.useDeprecatedNdk=true.

تعديل نص Gradle البرمجي للإصدار

افتح ملف build.gradle (Module:app) واتّبِع الإرشادات التالية لتعديل الإعدادات بما يتوافق مع متطلبات Navigation SDK، ويمكنك أيضًا ضبط خيارات التحسين.

الإعدادات المطلوبة لـ Navigation SDK
1. اضبط minSdkVersion على 24 أو أعلى.
2. اضبط targetSdkVersion على 36 أو أعلى.
3. أضِف إعداد dexOptions يزيد من javaMaxHeapSize.
4. اضبط الموقع الجغرافي للمكتبات الإضافية.
5. أضِف repositories وdependencies لحزمة تطوير البرامج (SDK) للتنقّل.
6. استبدِل أرقام الإصدارات في التبعيات بأحدث الإصدارات المتاحة.
الإعدادات الاختيارية لتقليل وقت الإنشاء
- فعِّل تقليص حجم الرموز البرمجية والموارد باستخدام R8/ProGuard لإزالة الرموز البرمجية والموارد غير المستخدَمة من التبعيات. إذا استغرقت خطوة R8/ProGuard وقتًا طويلاً للتشغيل، ننصحك بتفعيل ملفات DEX المتعددة لأعمال التطوير.
- تقليل عدد اللغات المترجَمة المضمّنة في الإصدار: اضبط resConfigs للغة واحدة أثناء عملية التطوير. بالنسبة إلى الإصدار النهائي، اضبط resConfigs للغات التي تستخدمها فعليًا. يتضمّن Gradle تلقائيًا سلاسل الموارد لجميع اللغات التي تتيحها حزمة تطوير البرامج (SDK) للتنقّل.
إضافة ميزة "إزالة التجميل اللغوي" لإتاحة استخدام Java8
- إذا كنت تنشئ تطبيقك باستخدام الإصدار 4.0.0 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android، يوسّع المكوّن الإضافي نطاق الدعم لاستخدام عدد من واجهات برمجة التطبيقات للغة Java 8. لمزيد من المعلومات، يُرجى الاطّلاع على دعم إزالة التجميل اللغوي في Java 8. اطّلِع على مثال مقتطف النص البرمجي للإصدار أدناه لمعرفة كيفية تجميع الخيارات والتبعية.
- استخدِم إصدارات Gradle والمكوّن الإضافي لنظام Gradle المتوافق مع Android ‏(AGP) ومكتبة Desugar التي تتوافق مع إصدار حزمة تطوير البرامج (SDK) للتنقّل. اطّلِع على الجدول التالي.
- يجب تفعيل مكتبة Desugar للوحدة app وأي وحدة تعتمد بشكل مباشر على حزمة تطوير البرامج (SDK) للتنقّل.

يسرد الجدول التالي إصدارات مكتبات Gradle وAGP وDesugar المطلوبة لكل إصدار من حزمة تطوير البرامج (SDK) لخدمة Navigation.

إصدار حزمة تطوير البرامج (SDK) للتنقّل	إصدار Gradle	إصدار "المكوّن الإضافي لنظام Gradle المتوافق مع Android"	مكتبة Desugar
الإصدار 8.0.0 أو الأحدث	9.1.0	9.0.1	`com.android.tools:desugar_jdk_libs_nio:2.1.5`
من 7.7.0 إلى 7.9.0	8.13	8.13.2	`com.android.tools:desugar_jdk_libs_nio:2.1.5`
من 7.3.0 إلى 7.6.0	8.11.1	8.10.0	`com.android.tools:desugar_jdk_libs_nio:2.0.3`

في ما يلي مثال على نص Gradle البرمجي لإنشاء التطبيق. يُرجى الاطّلاع على نماذج التطبيقات لمعرفة مجموعات التبعيات المحدّثة، لأنّ إصدار حزمة تطوير البرامج (SDK) للتنقّل الذي تستخدمه قد يكون متقدّمًا قليلاً أو متأخرًا عن هذه المستندات.

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.1.5'
}

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

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

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

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

في استوديو 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
}

افتح ملف 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'
}

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

ملاحظة: أدخِل الرمز كما هو موضّح. لا تستبدِل DEFAULT_API_KEY بمفتاح واجهة برمجة التطبيقات.
```
MAPS_API_KEY=DEFAULT_API_KEY
```
الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على ملف secrets.properties حتى لا تفشل عمليات الإنشاء. قد يحدث ذلك إذا نسخت التطبيق من نظام تحكّم في الإصدارات يحذف secrets.properties ولم تنشئ بعد ملف secrets.properties على جهازك لتقديم مفتاح واجهة برمجة التطبيقات.
يمكنك إضافة مفتاح واجهة برمجة التطبيقات إلى ملف AndroidManifest.xml أو تقديم مفتاح واجهة برمجة التطبيقات آليًا.
- أضِف مفتاح واجهة برمجة التطبيقات إلى AndroidManifest.xml:
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
        
```
  ملاحظة: com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على واجهات برمجة تطبيقات متعددة مستندة إلى "خرائط Google" على نظام Android الأساسي، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بالتنقّل على Android. لضمان التوافق مع الأنظمة القديمة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. يسمح هذا الاسم القديم بالمصادقة على الإصدار 2 من واجهة برمجة التطبيقات لخدمة "خرائط Google" لنظام التشغيل Android فقط. يمكن لأي تطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. في حال تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.
- قدِّم مفتاح واجهة برمجة التطبيقات آليًا:
  يوفّر المكوّن الإضافي Secrets Gradle المفتاح في فئة BuildConfig. في عملية إعداد تطبيقك (على سبيل المثال، في إجراء Application.onCreate())، استدعِ الإجراء على النحو التالي:
  Kotlin
  1. أضِف عبارات الاستيراد التالية:
    import com.google.android.libraries.navigation.NavigationApi
  2. أضِف ما يلي إلى طريقة Application.onCreate():
    NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)
  جافا
  1. أضِف عبارات الاستيراد التالية:
    import com.google.android.libraries.navigation.NavigationApi;
  2. أضِف ما يلي إلى طريقة Application.onCreate():
    NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
  ملاحظة: عند استخدام setApiKey()، يُرجى مراعاة ما يلي:
  - يُرجى تقديم مفتاح واجهة برمجة تطبيقات غير فارغ.
  - يجب استدعاء setApiKey() مرة واحدة فقط خلال فترة استخدام التطبيق. تُظهر الطريقة IllegalStateException إذا تم استدعاؤها أكثر من مرة.
  - يجب استدعاء setApiKey() قبل إعداد أي مكوّنات أخرى في حزمة تطوير البرامج (SDK) للتنقّل، مثل Navigator.
  - يؤدي المفتاح الذي تقدّمه باستخدام هذه الطريقة إلى إلغاء أي مفتاح واجهة برمجة تطبيقات في AndroidManifest.xml.
  - استخدِم الإصدار 7.6 أو إصدارًا أحدث من حزمة تطوير البرامج (SDK) الخاصة بـ Navigation.

في استوديو 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"
}

تضمين الإحالات المطلوبة في تطبيقك

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

يمكنك العثور على نص تحديد المصدر المطلوب وتراخيص البرامج المفتوحة المصدر في ملف ZIP الخاص بحزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android:

NOTICE.txt
LICENSES.txt

إذا كنت من عملاء Mobility أو Fleet Engine Deliveries

إذا كنت من عملاء Mobility أو Fleet Engine Deliveries، يمكنك الاطّلاع على مزيد من المعلومات حول الفوترة في مستندات Mobility. لمزيد من المعلومات حول تسجيل المعاملات، يُرجى الاطّلاع على إعداد الفوترة، تسجيل المعاملات الخاضعة للفوترة، إعداد التقارير، و تسجيل المعاملات الخاضعة للفوترة (Android).

التبعيات اليدوية (غير Gradle/Maven)

إذا لم يحلّ نظام الإصدار التبعيات الانتقالية (مثل Bazel)، أو إذا كنت تدمج ملفات AAR يدويًا، عليك إضافة هذه التبعيات إلى مشروعك. ويحلّ Gradle وMaven هذه التبعيات تلقائيًا.

androidx.datastore:datastore-core
androidx.datastore:datastore-guava
com.google.guava:listenablefuture
androidx.concurrent:concurrent-futures

إعداد مشروع "استوديو Android" تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

إضافة حزمة تطوير البرامج (SDK) للتنقّل إلى مشروعك

Gradle

Maven

Gradle

Maven

ضبط الإصدار

تعديل المواقع المحلية

تعديل نص Gradle البرمجي للإصدار

إضافة مفتاح واجهة برمجة التطبيقات إلى تطبيقك

Kotlin

Groovy

Kotlin

Groovy

Kotlin

جافا

Kotlin

Groovy

تضمين الإحالات المطلوبة في تطبيقك

إذا كنت من عملاء Mobility أو Fleet Engine Deliveries

التبعيات اليدوية (غير Gradle/Maven)

إعداد مشروع "استوديو Android"