يتوفّر حلّ الرحلات وعمليات التسليم عند الطلب حاليًا لشركاء محدّدين فقط.

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

بدء استخدام حزمة تطوير البرامج (SDK) للمستهلكين لنظام التشغيل Android

يمكنك استخدام حزمة تطوير البرامج (SDK) الخاصة بالمستهلك لإنشاء وتشغيل تطبيق مستهلِك أساسي متكامل من خلال خدمات الواجهة الخلفية لحلول الرحلات وعمليات التسليم عند الطلب. يمكنك إنشاء تطبيق Trip and Order Progress الذي يمكنه عرض رحلة نشطة والاستجابة لتحديثات الرحلة والتعامل مع أخطاء الرحلة.

ونظرًا لأن حزمة تطوير البرامج (SDK) الخاصة بالمستهلك لها بنية نموذجية، يمكنك استخدام الأجزاء من واجهة برمجة التطبيقات التي تريد استخدامها لتطبيقك المعيّن ودمجها مع واجهات برمجة التطبيقات الخاصة بك، وخدمات الخلفية التي يوفرها Fleet Engine، بالإضافة إلى واجهات برمجة التطبيقات الخاصة بمنصة خرائط Google.

الحد الأدنى لمتطلبات النظام

يجب أن يعمل الجهاز الجوّال بنظام Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) أو إصدار أحدث.

تكوين الإصدار والتبعيات

يتوفّر الإصدار 1.99.0 والإصدارات الأحدث من حزمة تطوير البرامج (SDK) للمستهلكين باستخدام Google Maven. المستودع. تم إيقاف قناة المستودع الخاص المستخدَمة سابقًا.

Gradle

أضِف ما يلي إلى ملف build.gradle:

repositories {
    ...
    google()
}

Maven

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

<project>
  ...
  <repositories>
    <repository>
      <id>google-maven-repository</id>
      <url>https://maven.google.com</url>
    </repository>
  </repositories>
  ...
</project>

تكوين المشروع

لاستخدام حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين لنظام التشغيل Android، يجب أن يستهدف التطبيق الإصدار 23 من minSdkVersion أو الإصدارات الأحدث

لتشغيل تطبيق تم إنشاؤه باستخدام حزمة تطوير البرامج (SDK) للمستهلكين، يمكن لنظام يجب أن يتضمّن الجهاز خدمات Google Play مثبت.

إعداد مشروع التطوير

لإعداد مشروع التطوير والحصول على مفتاح واجهة برمجة التطبيقات للمشروع على Google Cloud Console:

أنشِئ مشروعًا جديدًا على Google Cloud Console أو اختَر مشروعًا حاليًا لاستخدامه. مع حزمة SDK للمستهلكين. انتظر بضع دقائق حتى المشروع الجديد مرئيًا على Google Cloud Console.
من أجل تشغيل التطبيق التجريبي، يجب أن يمتلك مشروعك إذن الوصول إلى حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google". لأجهزة Android. في Google Cloud Console، اختَر واجهات برمجة التطبيقات الخدمات > المكتبة، ثم ابحث عن حزمة تطوير البرامج (SDK) للخرائط وفعّلها في Android
احصل على مفتاح واجهة برمجة تطبيقات للمشروع من خلال النقر واجهات برمجة التطبيقات الخدمات > بيانات الاعتماد > إنشاء بيانات الاعتماد > مفتاح واجهة برمجة التطبيقات. لمزيد من المعلومات حول الحصول على مفتاح واجهة برمجة التطبيقات، يمكنك الاطّلاع على الحصول على مفتاح واجهة برمجة التطبيقات

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

تتوفّر "حزمة تطوير البرامج (SDK) للمستهلكين" من خلال مستودع Maven خاص. تشير رسالة الأشكال البيانية يتضمّن المستودع ملفات نموذج كائن المشروع (pom.) في حزمة تطوير البرامج (SDK) ومستندات Javadocs. لإضافة حزمة تطوير البرامج (SDK) للمستهلكين إلى تطبيقك، يُرجى اتّباع الخطوات التالية:

اضبط بيئتك للوصول إلى مستودع Maven المضيف كما هو موضّح في. القسم السابق.

إذا كان لديك تهيئة مركزية لإدارة التبعية تم تعريفها في settings.gradle، يمكنك إيقافها على النحو التالي.
- إزالة مجموعة الرموز التالية في settings.gradle:
```
import org.gradle.api.initialization.resolve.RepositoriesMode
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
```

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

Gradle

أضِف ما يلي إلى build.gradle:

dependencies {
  ...
  implementation 'com.google.android.libraries.mapsplatform.transportation:transportation-consumer:VERSION_NUMBER'
}

Maven

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

<dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.mapsplatform.transportation</groupId>
    <artifactId>transportation-consumer</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

تعتمد حزمة تطوير البرامج (SDK) الخاصة بالمستهلك على حزمة تطوير البرامج (SDK) للخرائط. يتم تكوين هذه التبعية في بطريقة تتيح لم يتم تحديد إصدار حزمة تطوير البرامج (SDK) للخرائط بشكل صريح في ملف تهيئة الإصدار كما يلي، عند طرح إصدار جديد من الخرائط تم إصدار حزمة SDK للمستهلكين، ستستمر حزمة SDK للمستهلكين في استخدام الحد الأدنى إصدار حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" والمطلوب بواسطته.
Gradle
أضِف ما يلي إلى build.gradle:
```
dependencies {
  ...
  implementation 'com.google.android.gms:play-services-maps:18.1.0'
}
```
Maven
أضِف ما يلي إلى pom.xml:
```
<dependencies>
  ...
  <dependency>
    <groupId>com.google.android.gms</groupId>
    <artifactId>play-services-maps</artifactId>
    <version>18.1.0</version>
  </dependency>
</dependencies>
```

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

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

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

لتبسيط هذه المهمة، يمكنك استخدام المكوّن الإضافي السري لنظام Gradle المتوافق مع Android

لتثبيت المكوّن الإضافي وتخزين مفتاح واجهة برمجة التطبيقات:

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

رائع

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

Kotlin

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

افتح ملف build.gradle على مستوى التطبيق وأضِف الرمز التالي إلى العنصر plugins

رائع

id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'

Kotlin

id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")

إذا كنت تستخدم "استوديو Android" مزامنة مشروعك مع Gradle
افتح local.properties في دليل مستوى المشروع، ثم أضِف العنصر الرمز التالي. استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات الخاص بك.
```
MAPS_API_KEY=YOUR_API_KEY
```
في ملف 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}" />
```

يعرض المثال التالي بيانًا كاملاً لنموذج تطبيق:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.consumerapidemo">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/_AppTheme">

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

        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

إدراج عمليات تحديد المصدر المطلوبة في تطبيقك

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

يمكن العثور على معلومات التراخيص في "third_party_ Licenses.txt". تسجيل ملف AAR غير المؤرشف.

يُرجى الرجوع إلى https://developers.google.com/android/guides/opensource. حول كيفية تضمين إشعارات البرامج المفتوحة المصدر.

مصادقة حزمة تطوير البرامج (SDK) للمستهلك

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

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

يجب أن يشتمل الرمز المميّز للتفويض على مطالبة بقيمة tripid:TRIP_ID في عنوان authorization، حيث يكون TRIP_ID هو معرّف الرحلة. وهذا يمنح المستهلك وصول حزمة SDK إلى تفاصيل الرحلة، بما في ذلك موضع المركبة ومسارها والوقت المقدّر للوصول إليها

عمليات استدعاء الرمز المميّز للويب بتنسيق JSON

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

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

يحدد معاودة الاتصال بالرمز المميز للتفويض الرمز المميز للخدمة المطلوب لخدمة TripService. وتوفِّر أيضًا tripId المطلوبة. للسياق.

يوضّح مثال الرمز التالي كيفية تطبيق تفويض الرمز المميز.

Java

class JsonAuthTokenFactory implements AuthTokenFactory {

  private static final String TOKEN_URL =
      "https://yourauthserver.example/token";

  private static class CachedToken {
    String tokenValue;
    long expiryTimeMs;
    String tripId;
  }

  private CachedToken token;

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  @Override
  public String getToken(AuthTokenContext context) {
    // If there is no existing token or token has expired, go get a new one.
    String tripId = context.getTripId();
    if (tripId == null) {
      throw new RuntimeException("Trip ID is missing from AuthTokenContext");
    }
    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        !tripId.equals(token.tripId)) {
      token = fetchNewToken(tripId);
    }
    return token.tokenValue;
  }

  private static CachedToken fetchNewToken(String tripId) {
    String url = TOKEN_URL + "/" + tripId;
    CachedToken token = new CachedToken();

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();

      token.tokenValue = obj.get("ServiceToken").getAsString();
      token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong();

      /*
      * The expiry time could be an hour from now, but just to try and avoid
      * passing expired tokens, we subtract 5 minutes from that time.
      */
      token.expiryTimeMs -= 5 * 60 * 1000;
    } catch (IOException e) {
      /*
      * It's OK to throw exceptions here. The error listeners will receive the
      * error thrown here.
      */
      throw new RuntimeException("Could not get auth token", e);
    }
    token.tripId = tripId;

    return token;
  }
}

Kotlin

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: CachedToken? = null

  /*
  * This method is called on a background thread. Blocking is OK. However, be
  * aware that no information can be obtained from Fleet Engine until this
  * method returns.
  */
  override fun getToken(context: AuthTokenContext): String {
    // If there is no existing token or token has expired, go get a new one.
    val tripId = 
      context.getTripId() ?: 
        throw RuntimeException("Trip ID is missing from AuthTokenContext")

    if (token == null || System.currentTimeMillis() > token.expiryTimeMs ||
        tripId != token.tripId) {
      token = fetchNewToken(tripId)
    }

    return token.tokenValue
  }

  class CachedToken(
    var tokenValue: String? = "", 
    var expiryTimeMs: Long = 0,
    var tripId: String? = "",
  )

  private companion object {
    const val TOKEN_URL = "https://yourauthserver.example/token"

    fun fetchNewToken(tripId: String) {
      val url = "$TOKEN_URL/$tripId"
      val token = CachedToken()

      try {
        val reader = InputStreamReader(URL(url).openStream())

        reader.use {
          val obj = com.google.gson.JsonParser.parseReader(r).getAsJsonObject()

          token.tokenValue = obj.get("ServiceToken").getAsString()
          token.expiryTimeMs = obj.get("TokenExpiryMs").getAsLong()

          /*
          * The expiry time could be an hour from now, but just to try and avoid
          * passing expired tokens, we subtract 5 minutes from that time.
          */
          token.expiryTimeMs -= 5 * 60 * 1000
        }
      } catch (e: IOException) {
        /*
        * It's OK to throw exceptions here. The error listeners will receive the
        * error thrown here.
        */
        throw RuntimeException("Could not get auth token", e)
      }

      token.tripId = tripId

      return token
    }
  }
}

إعداد واجهة برمجة التطبيقات

قبل اتباع هذه الإجراءات، يفترض أنك قد مكنت والخدمات المناسبة وحزمة SDK للمستهلك.

الحصول على مثيل "`ConsumerApi`"

لاستخدام حزمة تطوير البرامج (SDK) للمستهلكين، يجب إعداد تطبيقك ConsumerApi بشكل غير متزامن. واجهة برمجة التطبيقات أحادية اللون. تستخدم طريقة الإعداد AuthTokenFactory. يُنتج المصنع رموز JWT المميزة للمستخدم عند الضرورة.

providerId هو رقم تعريف المشروع الخاص بمشروعك على Google Cloud. يمكنك الاطّلاع على دليل مستخدم Fleet Engine لمزيد من المعلومات حول إنشاء المشروع.

يجب أن ينفِّذ تطبيقك AuthTokenFactory كما هو موضّح في مصادقة حزمة تطوير البرامج (SDK) للمستهلك

Java

Task<ConsumerApi> consumerApiTask = ConsumerApi.initialize(
    this, "myProviderId", authTokenFactory);

consumerApiTask.addOnSuccessListener(
  consumerApi -> this.consumerApi = consumerApi);

Kotlin

val consumerApiTask =
  ConsumerApi.initialize(this, "myProviderId", authTokenFactory)

consumerApiTask?.addOnSuccessListener { consumerApi: ConsumerApi ->
  this@YourActivity.consumerApi = consumerApi
}

حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" وبرامج عرض الخرائط

يتوافق الإصدار 2.x.x من حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين مع حزمة تطوير البرامج (SDK) للخرائط للإصدار 18.1.0 والإصدارات الأحدث من نظام التشغيل Android. الجدول أدناه يلخّص العارض التلقائي حسب إصدار حزمة تطوير البرامج (SDK) لـ "خرائط Google" وإمكانية الدعم كلا العارضين. ومع ذلك، ننصحك باستخدام أحدث إصدار من العارض إذا كنت بحاجة إلى لاستخدام العارض القديم، يمكنك عندئذٍ تحديده بوضوح باستخدام MapsInitializer.initialize()

إصدار حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google"	التوافق مع أحدث إصدار من العارض	دعم العارض القديم	العارض التلقائي
الإصدار 18.1.0 والإصدارات الأقدم	نعم	نعم	الإصدار القديم*
V18.2.0	نعم	نعم	الأحدث

* مع طرح عارض الخرائط الجديد، سيتم ضبط "أحدث عارض" تلقائيًا.

إضافة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" كملحق

Gradle

أضِف ما يلي إلى build.gradle:

dependencies {
  //...
  implementation "com.google.android.gms:play-services-maps:VERSION_NUMBER"
}

Maven

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

 <dependencies>
   ...
   <dependency>
     <groupId>com.google.android.gms</groupId>
     <artifactId>play-services-maps</artifactId>
     <version>18.1.0</version>
   </dependency>
 </dependencies>

إعداد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" قبل إعداد حزمة تطوير البرامج (SDK) الخاصة بالمستهلك

يمكنك التواصل مع أحد أفراد الصف الدراسي "Activity" في "Application" أو بدء التشغيل. MapsInitializer.initialize() وانتظار ظهور نتيجة طلب العارض قبل الإعداد حزمة SDK للمستهلكين

java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.main);
  initViews();

  MapsInitializer.initialize(getApplicationContext(), Renderer.LATEST,
      new OnMapsSdkInitializedCallback() {
        @Override
        public void onMapsSdkInitialized(Renderer renderer) {
          switch (renderer) {
            case LATEST:
              Log.i("maps_renderer", "LATEST renderer");
              break;
            case LEGACY:
              Log.i("maps_renderer", "LEGACY renderer");
              break;
          }

          initializeConsumerSdk();
        }
      });
}

Kotlin

fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)
  initViews()

  MapsInitializer.initialize(
    getApplicationContext(), Renderer.LATEST,
    object : OnMapsSdkInitializedCallback() {
      fun onMapsSdkInitialized(renderer: Renderer?) {
        when (renderer) {
          LATEST -> Log.i("maps_renderer", "LATEST renderer")
          LEGACY -> Log.i("maps_renderer", "LEGACY renderer")
        }
        initializeConsumerSdk()
      }
    })
  }

إنشاء واجهة المستخدم

يمكنك استخدام إما ConsumerMapFragment أو ConsumerMapView لإنشاء واجهة مستخدم التطبيق. يتيح لك ConsumerMapFragment تحديد لخريطتك باستخدام Fragment بينما يتيح لك ConsumerMapView استخدام View مشاركة الرحلات الوظيفة هي نفسها في كل من ConsumerMapView ConsumerMapFragment، لذا يمكنك اختيار واحدة استنادًا إلى سواء كانت View أو إنّ Fragment أفضل لتطبيقك.

إتاحة استخدام عناصر واجهة برمجة التطبيقات 19 (KitKat) وVector القابل للرسم

إذا كان تصميم تطبيقك يتطلب دعمًا لأجهزة واجهة برمجة التطبيقات 19 (KitKat) والعناصر المتجهة للرسم، عليك إضافة الرمز التالي إلى سجلّ "نشاطك". يمتد هذا الرمز AppCompatActivity لاستخدام عناصر الرسومات المتجهة القابلة للرسم في حزمة تطوير البرامج (SDK) الخاصة بالمستهلك

Java

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

Kotlin

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

إضافة جزء الخريطة أو طريقة العرض

يمكنك إنشاء الخريطة لعرض مشاركة الرحلة في إما جزء من Android أو طريقة العرض التي تحدّدها في ملف XML لتخطيط تطبيقك (الموجودة في /res/layout). ويوفر الجزء (أو العرض) بعد ذلك إمكانية الوصول إلى الرحلة مشاركة الخريطة، والتي يمكن لتطبيقك الوصول إليها وتعديلها. توفر الخريطة أيضًا المقبض إلى ConsumerController، والذي يسمح لتطبيقك بالتحكم تخصيص تجربة مشاركة الرحلة.

مشاركة الخريطة ووحدة التحكّم في الرحلة

أنت تُعرّف خريطة مشاركة الرحلة إما على أنها جزء (باستخدام ConsumerMapFragment)، أو كطريقة عرض (باستخدام ConsumerMapView)، كما هو موضح في مثال التعليمة البرمجية التالي. يجب بعد ذلك استدعاء طريقة onCreate() getConsumerGoogleMapAsync(callback)، الذي يعرض ConsumerGoogleMap بشكل غير متزامن في رد الاتصال. يمكنك بعد ذلك استخدام ConsumerGoogleMap لعرض لمشاركة الرحلة، ويمكن تحديثها حسب الحاجة بواسطة تطبيقك.

ConsumerMapFragment

يمكنك تحديد الجزء في ملف XML لتخطيط التطبيق، كما هو موضّح في مثال التعليمة البرمجية التالي.

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
    android:id="@+id/consumer_map_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

يجب أن تأتي المكالمة إلى getConsumerGoogleMapAsync() من onCreate(). .

Java

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {

    // Find the ConsumerMapFragment.
    ConsumerMapFragment consumerMapFragment =
        (ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);

    // Initiate the callback that returns the map.
    if (consumerMapFragment != null) {
      consumerMapFragment.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          });
    }
  }

}

Kotlin

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    // Find the ConsumerMapFragment.
    val consumerMapFragment =
      fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment

    consumerMapFragment.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      }
    )
  }
}

ConsumerMapView

ويمكن استخدام العرض إما في جزء أو في نشاط، كما هو محدد في ملف XML.

<com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/consumer_map_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

يجب أن تكون المكالمة إلى getConsumerGoogleMapAsync() من onCreate(). ضِمن بالإضافة إلى معلمة معاودة الاتصال، فإنها تتطلب النشاط أو وGoogleMapOptions (التي يمكن أن تكون خالية)، التي تحتوي على الإعدادات لـ MapView. يجب أن تكون الفئة الأساسية للنشاط أو الجزء إما FragmentActivity أو Fragment فريق دعم (على التوالي)، بما أنّهما يوفّران حق الوصول إلى دورة حياته.

Java

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ConsumerMapView mapView = findViewById(R.id.consumer_map_view);

    if (mapView != null) {
      mapView.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          }, this, null);
    }
  }

}

Kotlin

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

    mapView.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        // The map returned in the callback is used to access the ConsumerController.
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      },
      /* fragmentActivity= */ this,
      /* googleMapOptions= */ null,
    )
  }
}

علامة MapView في كسر هي نفسها في المثال أعلاه، لـ MapView في نشاط ما، باستثناء أن الجزء يتضخم التنسيق الذي يتضمن MapView في طريقة الجزء onCreateView().

Java

public class MapViewInFragment extends Fragment {

  @Override
  public View onCreateView(
      @NonNull LayoutInflater layoutInflater,
      @Nullable ViewGroup viewGroup,
      @Nullable Bundle bundle) {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
  }

}

Kotlin

class MapViewInFragment : Fragment() {
  override fun onCreateView(
    layoutInflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?,
  ): View {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
  }
}

ضبط التكبير أو التصغير في الكاميرا للتركيز في رحلة

يعمل الزر "موقعي" التلقائي المُدمج في حزمة تطوير البرامج (SDK) للخرائط على تركيز الكاميرا على موقع الجهاز.

إذا كانت هناك جلسة "مشاركة الرحلة" نشطة، قد تحتاج إلى توسيط الكاميرا للتركيز على الرحلة بدلاً من موقع الجهاز.

حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين لنظام التشغيل Android المُدمَجة: Auto Camera

للسماح لك بالتركيز على الرحلة بدلاً من موقع الجهاز، توفر حزمة تطوير البرامج (SDK) الخاصة بالمستهلك ميزة "كاميرا تلقائية" مُفعَّلة تلقائيًا. يتم تكبير الكاميرا للتركيز على مسار مشاركة الرحلة نقطة طريق الرحلة التالية.

AutoCamera

تخصيص سلوك الكاميرا

إذا كنت بحاجة إلى التحكّم بشكل أكبر في سلوك الكاميرا، يمكنك إيقافه أو تفعيله. كاميرا تلقائية باستخدام ConsumerController.setAutoCameraEnabled().

تعرض ConsumerController.getCameraUpdate() حدود الكاميرا المقترَحة في هذه اللحظة. يمكنك بعد ذلك تقديم CameraUpdate كوسيطة إلى GoogleMap.moveCamera() أو GoogleMap.animateCamera().

الوصول إلى الخرائط ومشاركة الرحلات

لدعم مشاركة الرحلات والتفاعل مع الخرائط في تطبيقك، يجب أن يكون لديك إذن بالوصول إلى ConsumerGoogleMap و ConsumerController ConsumerMapFragment و ConsumerMapView تعرض كلتا النتيجتين بشكل غير متزامن ConsumerGoogleMap في ConsumerMapReadyCallback. يمكن إرجاع المشتريات مقابل ConsumerGoogleMap. ConsumerController من getConsumerController(). إِنْتَ يمكنه الوصول إلى ConsumerGoogleMap ConsumerController على النحو التالي.

Java

private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;

consumerMapView.getConsumerGoogleMapAsync(
    new ConsumerMapReadyCallback() {
      @Override
      public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
        consumerGoogleMap = consumerMap;
        consumerController = consumerMap.getConsumerController();
      }
    },
    this, null);

Kotlin

var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

consumerMapView.getConsumerGoogleMapAsync(
  object : ConsumerMapReadyCallback() {
    override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
      consumerGoogleMap = consumerMap
      consumerController = consumerMap.getConsumerController()
    },
    /* fragmentActivity= */ this,
    /* googleMapOptions= */ null,
  }
)

ConsumerGoogleMap

ConsumerGoogleMap هي فئة تضمين لـ صف واحد (GoogleMap). وهي تزود تطبيقك بإمكانية تنفيذ ما يلي: مع الخريطة باستخدام واجهة برمجة تطبيقات تعادل GoogleMap يسمح استخدام خريطة المستهلك للتطبيق والتنقّل للتفاعل بسلاسة مع نفس خريطة Google الأساسية. على سبيل المثال: يسمح النطاق GoogleMap بتسجيل معاودة الاتصال مرة واحدة فقط، ولكن يتيح ConsumerGoogleMap عمليات معاودة الاتصال المسجَّلة المزدوجة. تسمح عمليات معاودة الاتصال هذه لتطبيقك ومشاركة الرحلة بتسجيل عمليات معاودة الاتصال التي تكون تسمى بشكل تسلسلي.

ConsumerController

يوفّر ConsumerController إمكانية الوصول إلى وظائف مشاركة الرحلات، مثل مثل مراقبة الرحلات والتحكم في حالتها وتحديد المواقع.

إعداد ميزة "مشاركة الرحلة"

بعد تطابق الخلفية مع مستهلك مع مركبة، استخدِم "JourneySharingSession". لبدء مشاركة الرحلة وواجهة المستخدم. تعرض ميزة "مشاركة الرحلة" النتائج المطابقة وموقع المركبة ومسارها. بعد تنفيذ حزمة SDK في تطبيقك، يمكنك إضافة وظائف مراقبة الرحلات، والاستماع إلى التحديثات، والتعامل مع الأخطاء. تفترض الإجراءات التالية أن الخدمات الخلفية متاحة وأن خدمات مطابقة المستهلكين مع المركبات.

يمكنك تسجيل أداة استماع إلى عنصر TripModel للحصول على تفاصيل حول الرحلة، مثل الوقت المقدّر للوصول والمسافة التي ينبغي أن تسافرها المركبة قبل الوصول.

Java

// Create a TripModel instance for listening to updates to the trip specified by this trip name.
String tripName = ...;
TripModelManager tripModelManager = consumerApi.getTripModelManager();
TripModel tripModel = tripModelManager.getTripModel(tripName);

// Create a JourneySharingSession instance based on the TripModel.
JourneySharingSession session = JourneySharingSession.createInstance(tripModel);

// Add the JourneySharingSession instance on the map for updating the UI.
consumerController.showSession(session);

// Register for trip update events.
tripModel.registerTripCallback(new TripModelCallback() {
  @Override
  public void onTripETAToNextWaypointUpdated(
      TripInfo tripInfo, @Nullable Long timestampMillis) {
    // ...
  }

  @Override
  public void onTripActiveRouteRemainingDistanceUpdated(
      TripInfo tripInfo, @Nullable Integer distanceMeters) {
    // ...
  }

  // ...
});

Kotlin

// Create a TripModel instance for listening to updates to the trip specified by this trip name.
val tripName = "tripName"
val tripModelManager = consumerApi.getTripModelManager()
val tripModel = tripModelManager.getTripModel(tripName)

// Create a JourneySharingSession instance based on the TripModel.
val session = JourneySharingSession.createInstance(tripModel)

// Add the JourneySharingSession instance on the map for updating the UI.
consumerController.showSession(session)

// Register for trip update events.
tripModel.registerTripCallback(
  object : TripModelCallback() {
    override fun onTripETAToNextWaypointUpdated(
      tripInfo: TripInfo,
      timestampMillis: Long?,
    ) {
      // ...
    }

    override fun onTripActiveRouteRemainingDistanceUpdated(
      tripInfo: TripInfo,
      distanceMeters: Int?,
    ) {
      // ...
    }

  // ...
})

ضبط رحلتك باستخدام "TripModelOptions"

Java

// Set refresh interval to 2 seconds.
TripModelOptions tripOptions =
    TripModelOptions.builder().setRefreshIntervalMillis(2000).build();
tripModel.setTripModelOptions(tripOptions);

Kotlin

// Set refresh interval to 2 seconds.
val tripOptions = TripModelOptions.builder().setRefreshIntervalMillis(2000).build()
tripModel.setTripModelOptions(tripOptions)

إيقاف مشاركة الرحلة

تأكَّد من إيقاف مشاركة الرحلة عند عدم الحاجة إليها، مثلاً عند إتلاف نشاط المضيف. يؤدي إيقاف مشاركة الرحلة أيضًا إلى إيقاف طلبات الشبكة إلى Fleet Engine ومنع تسرُّب الذاكرة.

يوضح الرمز النموذجي التالي كيفية إيقاف مشاركة الرحلة.

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

  @Override
  protected void onDestroy() {
    super.onDestroy();

    if (journeySharingSession != null) {
      journeySharingSession.stop();
    }
  }
}

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

التعامل مع أخطاء الرحلة

تعرِض الطريقة onTripRefreshError الأخطاء التي تحدث أثناء تتبُّع الرحلة. ربط حزمة SDK للمستهلكين تتبع نفس إرشادات HTTP/RPC المحددة Google Cloud Platform تشمل الأخطاء الشائعة التي تظهر أثناء مراقبة الرحلة ما يلي:

HTTP	متوسط عائد النقرة	الوصف
400	INVALID_ARGUMENT	حدّد العميل اسم رحلة غير صالح. تشير رسالة الأشكال البيانية يجب أن يتّبع اسم الرحلة التنسيق `providers/{provider_id}/trips/{trip_id}` يجب أن يكون provider_id هو معرّف مشروع Google Cloud الذي يملكه مقدّم الخدمة
401	غير مصدَّق عليها	لم تتم مصادقة الطلب بسبب رمز JWT غير صالح. سيحدث هذا الخطأ إذا تم توقيع رمز JWT بدون رحلة أو انتهت صلاحية رمز JWT.
403	PERMISSION_DENIED	لا تتوفّر لدى العميل البيانات الكافية إذن. يحدث هذا الخطأ إذا كان JWT الرمز غير صالح، فلا يمتلك العميل أو لم يتم تفعيل واجهة برمجة التطبيقات بمشروع العميل. قد يكون رمز JWT المميز غير متوفّر أو يتم توقيع الرمز المميّز مع رحلة رقم تعريف لا يتطابق مع معرّف الرحلة المطلوب.
429	RESOURCE_EXHAUSTED	تصبح حصة الموارد صفرًا أو معدّل من الزيارات تتجاوز الحد المسموح به.
503	UNAVAILABLE	الخدمة غير متاحة. وعادةً ما يكون الخادم انخفضت.
504	DEADLINE_EXCEEDED	تجاوزت الموعد النهائي للطلب. سيؤدي هذا إلى لا تحدث إلا إذا حدد المتصل موعدًا نهائيًا وهو أقصر من القيمة الافتراضية للطريقة موعد نهائي (أي أنّ الموعد النهائي المطلوب غير بما يكفي للخادم لمعالجة الطلب) ولم ينتهِ الطلب في الموعد النهائي.

لمزيد من المعلومات، يُرجى مراجعة معالجة خطأ حزمة SDK للمستهلك:

بدء استخدام حزمة تطوير البرامج (SDK) للمستهلكين لنظام التشغيل Android

الحد الأدنى لمتطلبات النظام

تكوين الإصدار والتبعيات

Gradle

Maven

تكوين المشروع

إعداد مشروع التطوير

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

Gradle

Maven

Gradle

Maven

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

رائع

Kotlin

رائع

Kotlin

إدراج عمليات تحديد المصدر المطلوبة في تطبيقك

مصادقة حزمة تطوير البرامج (SDK) للمستهلك

عمليات استدعاء الرمز المميّز للويب بتنسيق JSON

Java

Kotlin

إعداد واجهة برمجة التطبيقات

الحصول على مثيل "ConsumerApi"

Java

Kotlin

حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" وبرامج عرض الخرائط

إضافة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" كملحق

Gradle

Maven

إعداد حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" قبل إعداد حزمة تطوير البرامج (SDK) الخاصة بالمستهلك

java

Kotlin

إنشاء واجهة المستخدم

إتاحة استخدام عناصر واجهة برمجة التطبيقات 19 (KitKat) وVector القابل للرسم

Java

Kotlin

إضافة جزء الخريطة أو طريقة العرض

مشاركة الخريطة ووحدة التحكّم في الرحلة

ConsumerMapFragment

Java

Kotlin

ConsumerMapView

Java

Kotlin

Java

Kotlin

ضبط التكبير أو التصغير في الكاميرا للتركيز في رحلة

حزمة تطوير البرامج (SDK) الخاصة بالمستهلكين لنظام التشغيل Android المُدمَجة: Auto Camera

تخصيص سلوك الكاميرا

الوصول إلى الخرائط ومشاركة الرحلات

Java

Kotlin

ConsumerGoogleMap

ConsumerController

إعداد ميزة "مشاركة الرحلة"

Java

Kotlin

Java

Kotlin

إيقاف مشاركة الرحلة

Java

Kotlin

التعامل مع أخطاء الرحلة

الحصول على مثيل "`ConsumerApi`"