راه حل سواری و تحویل بر اساس تقاضا در حال حاضر فقط برای شرکای منتخب در دسترس است.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

شروع کار با Driver SDK برای Android، شروع به کار با Driver SDK برای Android

می توانید از Driver SDK برای ارائه ناوبری و ردیابی پیشرفته به برنامه سفر و پیشرفت سفارش خود استفاده کنید. Driver SDK به‌روزرسانی‌های مکان خودرو و وظایف را به موتور ناوگان راه‌حل بر اساس تقاضا و تحویل ارائه می‌کند.

Driver SDK خدمات Fleet Engine و خدمات سفارشی شما را از موقعیت و وضعیت خودرو آگاه می کند. برای مثال، وسیله نقلیه می‌تواند ONLINE یا OFFLINE باشد، و مکان وسیله نقلیه با پیشرفت سفر تغییر می‌کند.

کمترین سیستم مورد نیاز

دستگاه همراه باید دارای Android 6.0 (سطح API 23) یا بالاتر باشد.

پیکربندی Maven

درایور SDK نسخه 4.99 و جدیدتر از مخزن Google Maven در دسترس است.

گریدل

موارد زیر را به فایل build.gradle خود اضافه کنید:

repositories {
    ...
    google()
}

ماون

موارد زیر را به فایل pom.xml خود اضافه کنید:

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

پیکربندی پروژه

برای استفاده از Driver SDK، برنامه شما باید minSdkVersion 23 یا بالاتر را هدف قرار دهد.

برای اجرای برنامه‌ای که با Driver SDK ساخته شده است، دستگاه Android باید سرویس‌های Google Play را نصب کرده باشد.

پروژه توسعه خود را تنظیم کنید

برای راه‌اندازی پروژه توسعه خود و دریافت کلید API برای پروژه در Google Cloud Console:

یک پروژه جدید Google Cloud Console ایجاد کنید یا یک پروژه موجود را برای استفاده با Driver SDK انتخاب کنید. چند دقیقه صبر کنید تا پروژه جدید در Google Cloud Console قابل مشاهده باشد.
برای اجرای برنامه آزمایشی، پروژه شما باید به Maps SDK برای اندروید دسترسی داشته باشد. در Google Cloud Console، APIs & Services > Library را انتخاب کنید، سپس Maps SDK for Android را جستجو و فعال کنید.
با انتخاب APIs & Services > Credentials > Create credentials > API key، یک کلید API برای پروژه دریافت کنید. برای اطلاعات بیشتر درباره دریافت کلید API، به دریافت کلید API مراجعه کنید.

Driver SDK را به برنامه خود اضافه کنید

Driver SDK از مخزن Google Maven در دسترس است. این مخزن شامل فایل‌های Project Object Model (.pom) SDK و Javadocs است. برای افزودن Driver SDK به برنامه خود:

وابستگی زیر را به پیکربندی Gradle یا Maven خود اضافه کنید و جای جای VERSION_NUMBER را جایگزین نسخه مورد نظر Driver SDK کنید.

گریدل

موارد زیر را به build.gradle خود اضافه کنید:

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

ماون

موارد زیر را به pom.xml خود اضافه کنید:

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

کلید API را به برنامه خود اضافه کنید

هنگامی که Driver SDK را به برنامه خود اضافه کردید، کلید API را به برنامه خود اضافه کنید. شما باید از کلید API پروژه که هنگام راه اندازی پروژه توسعه خود به دست آورده اید استفاده کنید.

این بخش نحوه ذخیره کلید API خود را توضیح می دهد تا بتواند با امنیت بیشتری توسط برنامه شما ارجاع دهد. شما نباید کلید API خود را در سیستم کنترل نسخه خود بررسی کنید. باید در فایل local.properties که در دایرکتوری ریشه پروژه شما قرار دارد ذخیره شود. برای اطلاعات بیشتر در مورد فایل local.properties ، فایل های ویژگی های Gradle را ببینید.

برای ساده‌سازی این کار، می‌توانید از افزونه Secrets Gradle برای اندروید استفاده کنید.

برای نصب افزونه و ذخیره کلید API:

فایل build.gradle سطح ریشه خود را باز کنید و کد زیر را به عنصر dependencies در زیر buildscript اضافه کنید.

شیار

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

کاتلین

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'
```
کاتلین
```
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
```
اگر از Android Studio استفاده می کنید، پروژه خود را با Gradle همگام کنید .
local.properties را در دایرکتوری سطح پروژه خود باز کنید و کد زیر را اضافه کنید. کلید API خود را جایگزین 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.driverapidemo">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_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>

اسناد مورد نیاز را در برنامه خود قرار دهید

اگر از Driver SDK در برنامه خود استفاده می کنید، باید متن منبع و مجوزهای منبع باز را به عنوان بخشی از بخش اعلامیه های قانونی برنامه خود اضافه کنید. بهتر است انتساب‌ها را به‌عنوان یک آیتم منوی مستقل یا به‌عنوان بخشی از یک آیتم درباره منو درج کنید.

می‌توانید متن منبع مورد نیاز و مجوزهای منبع باز را در فایل فشرده Driver SDK بیابید:

NOTICE.txt
LICENSES.txt

وابستگی ها

اگر از ProGuard برای بهینه سازی ساخت های خود استفاده می کنید، ممکن است لازم باشد خطوط زیر را به فایل پیکربندی ProGuard خود اضافه کنید:

-dontwarn com.google.**
-dontwarn okio.**

حداقل سطح API پشتیبانی شده 23 است.

راه اندازی SDK

شناسه ارائه دهنده (معمولاً شناسه پروژه Google Cloud) برای مقداردهی اولیه شی DriverContext مورد نیاز است. برای جزئیات بیشتر درباره راه‌اندازی پروژه Google Cloud، به احراز هویت و مجوز مراجعه کنید.

قبل از استفاده از Driver SDK، ابتدا باید Navigation SDK را مقداردهی اولیه کنید. برای مقداردهی اولیه SDK:

یک شی Navigator را از NavigationApi دریافت کنید.

جاوا

NavigationApi.getNavigator(
    this, // Activity
    new NavigationApi.NavigatorListener() {
      @Override
      public void onNavigatorReady(Navigator navigator) {
        // Keep a reference to the Navigator (used to configure and start nav)
        this.navigator = navigator;
      }
    }
);

کاتلین

NavigationApi.getNavigator(
  this, // Activity
  object : NavigatorListener() {
    override fun onNavigatorReady(navigator: Navigator) {
      // Keep a reference to the Navigator (used to configure and start nav)
      this@myActivity.navigator = navigator
    }
  },
)

یک شی DriverContext ایجاد کنید و فیلدهای مورد نیاز را پر کنید.

جاوا

DriverContext driverContext = DriverContext.builder(application)
    .setProviderId(providerId)
    .setVehicleId(vehicleId)
    .setAuthTokenFactory(authTokenFactory)
    .setNavigator(navigator)
    .setRoadSnappedLocationProvider(
        NavigationApi.getRoadSnappedLocationProvider(application))
    .build();

کاتلین

val driverContext =
  DriverContext.builder(application)
    .setProviderId(providerId)
    .setVehicleId(vehicleId)
    .setAuthTokenFactory(authTokenFactory)
    .setNavigator(navigator)
    .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(application))
    .build()

از شی DriverContext برای مقداردهی اولیه *DriverApi استفاده کنید.

جاوا

RidesharingDriverApi ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext);

کاتلین

val ridesharingDriverApi = RidesharingDriverApi.createInstance(driverContext)

RidesharingVehicleReporter را از شی API دریافت کنید. ( *VehicleReporter NavigationVehicleReporter را گسترش می دهد.)

جاوا

RidesharingVehicleReporter vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter();

کاتلین

val vehicleReporter = ridesharingDriverApi.getRidesharingVehicleReporter()

احراز هویت با `AuthTokenFactory`

وقتی Driver SDK به‌روزرسانی‌های مکان را تولید می‌کند، باید این به‌روزرسانی‌ها را به سرور Fleet Engine ارسال کند. برای احراز هویت این درخواست‌ها، Driver SDK با یک نمونه از AuthTokenFactory ارائه‌شده توسط تماس‌گیرنده تماس می‌گیرد. کارخانه مسئول تولید توکن های احراز هویت در زمان به روز رسانی مکان است.

اینکه دقیقاً چگونه توکن ها تولید می شوند به موقعیت هر توسعه دهنده بستگی دارد. با این حال، پیاده سازی احتمالاً به موارد زیر نیاز دارد:

یک نشانه احراز هویت، احتمالاً با فرمت JSON، از یک سرور HTTPS واکشی کنید
رمز را تجزیه و کش کنید
زمانی که توکن منقضی شد، آن را به روز کنید

برای جزئیات بیشتر توکن‌های مورد انتظار توسط سرور Fleet Engine، به ایجاد یک نشانه وب JSON (JWT) برای مجوز مراجعه کنید.

در اینجا یک پیاده سازی اسکلت یک AuthTokenFactory است:

جاوا

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String token;  // initially null
  private long expiryTimeMs = 0;

  // This method is called on a thread whose only responsibility is to send
  // location updates. Blocking is OK, but just know that no location updates
  // can occur until this method returns.
  @Override
  public String getToken(AuthTokenContext authTokenContext) {
    if (System.currentTimeMillis() > expiryTimeMs) {
      // The token has expired, go get a new one.
      fetchNewToken(authTokenContext.getVehicleId());
    }
    return token;
  }

  private void fetchNewToken(String vehicleId) {
    String url =
        new Uri.Builder()
            .scheme("https")
            .authority("yourauthserver.example")
            .appendPath("token")
            .appendQueryParameter("vehicleId", vehicleId)
            .build()
            .toString();

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
      token = obj.get("Token").getAsString();
      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 10 minutes from that time.
      expiryTimeMs -= 10 * 60 * 1000;
    } catch (IOException e) {
      // It's OK to throw exceptions here. The StatusListener you passed to
      // create the DriverContext class will be notified and passed along the failed
      // update warning.
      throw new RuntimeException("Could not get auth token", e);
    }
  }
}

کاتلین

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: String = ""
  private var expiryTimeMs: Long = 0

  // This method is called on a thread whose only responsibility is to send
  // location updates. Blocking is OK, but just know that no location updates
  // can occur until this method returns.
  override fun getToken(context: AuthTokenContext): String {
    if (System.currentTimeMillis() > expiryTimeMs) {
      // The token has expired, go get a new one.
      fetchNewToken(authTokenContext.getVehicleId())
    }
     return token
  }

  fun fetchNewToken(vehicleId: String) {
    val url =
      Uri.Builder()
        .scheme("https")
        .authority("yourauthserver.example")
        .appendPath("token")
        .appendQueryParameter("vehicleId", vehicleId)
        .build()
        .toString()

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

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

        token = obj.get("ServiceToken").getAsString()
        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 10 minutes from that time.
        expiryTimeMs -= 10 * 60 * 1000
      }
    } catch (e: IOException) {
      // It's OK to throw exceptions here. The StatusListener you passed to
      // create the DriverContext class will be notified and passed along the failed
      // update warning.
      throw RuntimeException("Could not get auth token", e)
    }
  }
}

این پیاده‌سازی خاص از سرویس گیرنده جاوا HTTP داخلی برای واکشی توکن با فرمت JSON از سرور احراز هویت توسعه‌دهنده استفاده می‌کند. رمز برای استفاده مجدد ذخیره می شود. اگر توکن قدیمی در 10 دقیقه از زمان انقضای خود باشد، توکن دوباره واکشی می شود.

پیاده سازی شما ممکن است کارها را متفاوت انجام دهد، مانند استفاده از یک رشته پس زمینه برای به روز کردن نشانه ها.

استثناها در AuthTokenFactory به عنوان گذرا تلقی می شوند مگر اینکه به طور مکرر اتفاق بیفتند. پس از چند بار تلاش، Driver SDK فرض می کند که خطا دائمی است و تلاش برای ارسال به روز رسانی را متوقف می کند.

گزارش وضعیت و خطا با `StatusListener`

از آنجایی که Driver SDK اقداماتی را در پس‌زمینه انجام می‌دهد، از StatusListener برای راه‌اندازی اعلان‌ها هنگام وقوع رویدادهای خاصی مانند خطاها، هشدارها یا پیام‌های اشکال‌زدایی استفاده کنید. خطاها ممکن است ماهیت گذرا داشته باشند (مانند BACKEND_CONNECTIVITY_ERROR )، یا ممکن است باعث توقف دائمی به‌روزرسانی‌های مکان شوند (مانند VEHICLE_NOT_FOUND که نشان دهنده یک خطای پیکربندی است).

شما یک پیاده سازی اختیاری StatusListener مانند موارد زیر ارائه می کنید:

جاوا

class MyStatusListener implements StatusListener {
  /** Called when background status is updated, during actions such as location reporting. */
  @Override
  public void updateStatus(
      StatusLevel statusLevel, StatusCode statusCode, String statusMsg) {
    // Status handling stuff goes here.
    // StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
    // StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
    // BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
  }
}

کاتلین

class MyStatusListener : StatusListener() {
  /** Called when background status is updated, during actions such as location reporting. */
  override fun updateStatus(statusLevel: StatusLevel, statusCode: StatusCode, statusMsg: String) {
    // Status handling stuff goes here.
    // StatusLevel may be DEBUG, INFO, WARNING, or ERROR.
    // StatusCode may be DEFAULT, UNKNOWN_ERROR, VEHICLE_NOT_FOUND,
    // BACKEND_CONNECTIVITY_ERROR, or PERMISSION_DENIED.
  }
}

نکاتی در مورد SSL/TLS

در داخل، اجرای Driver SDK از SSL/TLS برای برقراری ارتباط امن با سرور Fleet Engine استفاده می‌کند. نسخه‌های قدیمی‌تر Android (نسخه‌های API 19 یا پایین‌تر) ممکن است به یک وصله SecurityProvider برای برقراری ارتباط با سرور نیاز داشته باشند. برای اطلاعات بیشتر در مورد کار با SSL در اندروید باید این مقاله را ببینید. این مقاله همچنین حاوی نمونه کدهایی برای وصله ارائه دهنده امنیت است.

فعال کردن به‌روزرسانی‌های مکان

هنگامی که یک نمونه *VehicleReporter دارید، فعال کردن به‌روزرسانی‌های موقعیت مکانی ساده است:

جاوا

RidesharingVehicleReporter reporter = ...;

reporter.enableLocationTracking();

کاتلین

val reporter = ...

reporter.enableLocationTracking()

هنگامی که وضعیت خودرو ONLINE است، به‌روزرسانی‌های مکان در یک بازه زمانی منظم ارسال می‌شوند. توجه داشته باشید که فراخوانی reporter.enableLocationTracking() به طور خودکار وضعیت خودرو را روی ONLINE تنظیم نمی کند. شما باید وضعیت خودرو را به صراحت تنظیم کنید .

به طور پیش فرض فاصله گزارش دهی ثانیه است. فاصله گزارش را می توان با reporter.setLocationReportingInterval(long, TimeUnit) تغییر داد. حداقل فاصله به روز رسانی پشتیبانی شده 5 ثانیه است. به‌روزرسانی‌های مکرر ممکن است منجر به درخواست‌ها و خطاهای کندتر شود.

غیرفعال کردن به‌روزرسانی‌های مکان

وقتی شیفت راننده تمام شد، می‌توان با تماس با DeliveryVehicleReporter.disableLocationTracking یا RidesharingVehicleReporter.disableLocationTracking ، به‌روزرسانی‌های مکان را متوقف کرد و خودرو را آفلاین علامت‌گذاری کرد.

این تماس باعث می‌شود که یک به‌روزرسانی نهایی برای تحویل فوری برنامه‌ریزی شود، که نشان می‌دهد خودرو آفلاین است. این به روز رسانی شامل موقعیت مکانی کاربر نخواهد بود.

تنظیم وضعیت خودرو

وقتی به‌روزرسانی موقعیت مکانی فعال است، تنظیم وضعیت خودرو روی ONLINE ، خودرو را برای جستجوهای SearchVehicles در دسترس قرار می‌دهد. به طور مشابه، علامت گذاری یک وسیله نقلیه به عنوان OFFLINE ، وسیله نقلیه را به عنوان غیرقابل دسترس علامت گذاری می کند.

شما می توانید وضعیت خودرو را در سمت سرور تنظیم کنید (به به روز رسانی خودرو مراجعه کنید)، یا مستقیماً در Driver SDK:

جاوا

RidesharingVehicleReporter reporter = ...;

reporter.enableLocationTracking();
reporter.setVehicleState(VehicleState.ONLINE);

کاتلین

val reporter = ...

reporter.enableLocationTracking()
reporter.setVehicleState(VehicleState.ONLINE)

هنگامی که به‌روزرسانی‌های موقعیت مکانی فعال می‌شوند، تماسی با setVehicleState در به‌روزرسانی مکان بعدی منتشر می‌شود.

علامت گذاری یک وسیله نقلیه به عنوان ONLINE هنگامی که ردیابی موقعیت مکانی فعال نیست منجر به یک IllegalStateException می شود. زمانی که ردیابی موقعیت هنوز فعال یا صریحاً غیرفعال نشده باشد، خودرو را می‌توان به‌عنوان OFFLINE علامت‌گذاری کرد. این باعث بروز رسانی فوری می شود. تماس با RidesharingVehicleReporter.disableLocationTracking() وضعیت خودرو را روی OFFLINE تنظیم می کند.

توجه داشته باشید که setVehicleState بلافاصله برمی‌گردد و به‌روزرسانی‌ها در رشته به‌روزرسانی مکان انجام می‌شوند. مانند رسیدگی به خطاهای به‌روزرسانی مکان‌ها، خطاهای به‌روزرسانی وضعیت خودرو با استفاده از مجموعه StatusListener که به صورت اختیاری در DriverContext ارائه شده است منتشر می‌شوند.

شروع کار با Driver SDK برای Android، شروع به کار با Driver SDK برای Android

کمترین سیستم مورد نیاز

پیکربندی Maven

گریدل

ماون

پیکربندی پروژه

پروژه توسعه خود را تنظیم کنید

Driver SDK را به برنامه خود اضافه کنید

گریدل

ماون

کلید API را به برنامه خود اضافه کنید

شیار

کاتلین

شیار

کاتلین

اسناد مورد نیاز را در برنامه خود قرار دهید

وابستگی ها

راه اندازی SDK

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

جاوا

کاتلین

احراز هویت با AuthTokenFactory

جاوا

کاتلین

گزارش وضعیت و خطا با StatusListener

جاوا

کاتلین

نکاتی در مورد SSL/TLS

فعال کردن به‌روزرسانی‌های مکان

جاوا

کاتلین

غیرفعال کردن به‌روزرسانی‌های مکان

تنظیم وضعیت خودرو

جاوا

کاتلین

احراز هویت با `AuthTokenFactory`

گزارش وضعیت و خطا با `StatusListener`