تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

إضافة حزمة Navigation SDK إلى مشروعك

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

أضِف الاعتمادية التالية إلى إعدادات Gradle أو Maven، مع استبدال العنصر النائب VERSION_NUMBER بالإصدار المطلوب من Navigation 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 لم يعُد ضروريًا.

إذا كانت لديك أي عناصر تابعة تستخدم حزمة تطوير البرامج (SDK) للخرائط، عليك استبعاد العنصر التابع في كل عنصر تابع تم الإعلان عنه ويعتمد على حزمة تطوير البرامج (SDK) للخرائط.

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>

ضبط عملية الإنشاء

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

تعديل الخصائص المحلية

في مجلد نصوص Gradle البرمجية، افتح الملف local.properties وأضِف android.useDeprecatedNdk=true.

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

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

الإعدادات المطلوبة لحزمة تطوير البرامج للتنقّل
1. اضبط قيمة minSdkVersion على 23 أو أعلى.
2. اضبط targetSdkVersion على 34 أو أعلى.
3. أضِف إعداد dexOptions يزيد من javaMaxHeapSize.
4. اضبط الموقع الجغرافي للمكتبات الإضافية.
5. أضِف repositories وdependencies إلى حزمة تطوير البرامج للتنقّل.
6. استبدِل أرقام الإصدارات في التبعيات بأحدث الإصدارات المتاحة.
إعدادات اختيارية لتقليل وقت الإنشاء
- فعِّل تقليص الرموز وتقليص الموارد باستخدام R8/ProGuard لإزالة الرموز والموارد غير المستخدَمة من التبعيات. إذا استغرقت خطوة R8/ProGuard وقتًا طويلاً جدًا، ننصحك بتفعيل التطبيق المتعدد لأغراض التطوير.
- قلِّل عدد ترجمات اللغات المضمّنة في الإصدار: اضبط resConfigs على لغة واحدة أثناء التطوير. بالنسبة إلى الإصدار النهائي، اضبط resConfigs على اللغات التي تستخدمها فعليًا. يتضمّن Gradle تلقائيًا سلاسل موارد لجميع اللغات التي تتوافق مع Navigation SDK.
إضافة عملية إزالة التشفير لتوفير توافق مع Java 8
- إذا كنت تنشئ تطبيقك باستخدام الإصدار 4.0.0 أو إصدار أحدث من إضافة Android Gradle، ستوفّر الإضافة إمكانية استخدام عدد من واجهات برمجة التطبيقات للغة Java 8. راجِع توافق Java 8 مع إزالة التشويش للحصول على مزيد من المعلومات. اطّلِع على مثال مقتطف نص برمجي أدناه حول خيارات التجميع والتبعيات.
- ننصحك باستخدام الإصدار 8.4 من Gradle والإصدار 8.3.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android ومكتبة Desugar com.android.tools:desugar_jdk_libs_nio:2.0.3. يتوافق هذا الإعداد مع الإصدار 6.0.0 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android والإصدارات الأحدث.
- يجب تفعيل مكتبة Desugar للوحدة app وأي وحدة تعتمد بشكل مباشر على حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation.

في ما يلي مثال على نص برمجة Gradle لإنشاء التطبيق. راجِع التطبيقات النموذجية للحصول على مجموعات محدَّثة من التبعيات، لأنّ إصدار حزمة Navigation 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.0.3'
}

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

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

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

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

في Android Studio، افتح ملف build.gradle.kts أو build.gradle ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

Kotlin

buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

Groovy

buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

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

Kotlin

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

Groovy

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

في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، تأكَّد من ضبط قيمتَي targetSdk وcompileSdk على 34.
مزامنة مشروعك مع Gradle
افتح ملف secrets.properties في الدليل ذي المستوى الأعلى، ثم أضِف الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. خزِّن المفتاح في هذا الملف لأنّ secrets.properties مستبعد من إمكانية التحقّق من نظام التحكّم في الإصدار.
ملاحظة: إذا لم يكن ملف 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، انتقِل إلى com.google.android.geo.API_KEY وعدِّل android:value attribute. إذا لم تكن العلامة <meta-data> متوفّرة، أنشئها كعنصر تابع للعلامة <application>.
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```
ملاحظة: ‫com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على عدة واجهات برمجة تطبيقات مستندة إلى "خرائط Google" على نظام التشغيل Android، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation API لنظام التشغيل Android. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا الاسم com.google.android.maps.v2.API_KEY. يتيح هذا الاسم القديم المصادقة على الإصدار 2 من واجهة برمجة التطبيقات "خرائط Google" لنظام التشغيل Android فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

في Android Studio، افتح ملف 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 same folder as the 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 same folder as the 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 الخاص بـ "حزمة تطوير البرامج للتنقّل على أجهزة Android" باتّباع الخطوات التالية:

NOTICE.txt
LICENSES.txt

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

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

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

إضافة حزمة Navigation SDK إلى مشروعك

Gradle

Maven

Gradle

Maven

ضبط عملية الإنشاء

تعديل الخصائص المحلية

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

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

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Groovy

تضمين الإشارات المطلوبة إلى المصدر في تطبيقك

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

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