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

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

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

پیکربندی ساخت و وابستگی ها

درایور 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:

  1. یک پروژه جدید Google Cloud Console ایجاد کنید یا یک پروژه موجود را برای استفاده با Driver SDK انتخاب کنید. چند دقیقه صبر کنید تا پروژه جدید در Google Cloud Console قابل مشاهده باشد.

  2. برای اجرای برنامه آزمایشی، پروژه شما باید به Maps SDK برای Android دسترسی داشته باشد. در Google Cloud Console، APIs & Services > Library را انتخاب کنید، سپس Maps SDK for Android را جستجو و فعال کنید.

  3. با انتخاب APIs & Services > Credentials > Create credentials > API key، یک کلید API برای پروژه دریافت کنید. برای اطلاعات بیشتر درباره دریافت کلید API، به دریافت کلید API مراجعه کنید.

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

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

  1. وابستگی زیر را به پیکربندی 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.driver</groupId>
        <artifactId>transportation-driver</artifactId>
        <version>[VERSION_NUMBER]</version>
      </dependency>
    </dependencies>
    
  2. درایور SDK به Navigation SDK بستگی دارد، این وابستگی به گونه ای پیکربندی شده است که در صورت نیاز به نسخه خاصی از Navigation SDK، باید به صراحت در فایل پیکربندی ساخت مانند زیر تعریف شود، حذف بلوک کد ذکر شده پروژه را فعال می کند. همیشه آخرین نسخه Navigation SDK را در نسخه اصلی دانلود کنید. توجه داشته باشید که رفتارهای ترکیبی آخرین نسخه‌های Driver SDK و Navigation SDK قبل از انتشار تحت آزمایش‌های دقیق قرار گرفته‌اند.

    پیکربندی وابستگی محیط های توسعه و انتشار خود را بر این اساس ترتیب دهید.

    گریدل

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

    dependencies {
      ...
      implementation 'com.google.android.libraries.navigation:navigation:5.0.0'
    }
    

    ماون

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

    <dependencies>
      ...
      <dependency>
        <groupId>com.google.android.libraries.navigation</groupId>
        <artifactId>navigation</artifactId>
        <version>5.0.0</version>
      </dependency>
    </dependencies>
    

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

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

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

برای ساده کردن این کار، از افزونه Secrets Gradle برای Android استفاده کنید. این روش را برای نصب افزونه Secrets Gradle و ذخیره ایمن کلید API خود دنبال کنید.

  1. فایل 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")
        }
    }
    
  2. فایل build.gradle سطح برنامه خود را باز کنید و کد زیر را به عنصر plugins اضافه کنید.

    شیار

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

    کاتلین

    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    
  3. پروژه خود را با Gradle همگام سازی کنید .

  4. local.properties را در دایرکتوری سطح پروژه خود باز کنید و کد زیر را اضافه کنید. حتماً کلید API خود را جایگزین YOUR_API_KEY کنید.

    MAPS_API_KEY=YOUR_API_KEY
    
  5. در فایل 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 در برنامه خود استفاده می کنید، باید متن منبع و مجوزهای منبع باز را به عنوان بخشی از بخش اعلامیه های قانونی برنامه خود اضافه کنید. بهتر است انتساب‌ها را به‌عنوان یک آیتم منوی مستقل یا به‌عنوان بخشی از یک آیتم درباره منو درج کنید.

اطلاعات مجوزها را می توان در فایل "third_party_licenses.txt" در فایل AAR بایگانی نشده پیدا کرد.

در مورد نحوه گنجاندن اعلامیه های منبع باز به https://developers.google.com/android/guides/opensource مراجعه کنید.

وابستگی ها

Driver SDK از gRPC برای برقراری ارتباط با سرور Fleet Engine استفاده می کند. اگر قبلاً gRPC را وارد نکرده‌اید، ممکن است لازم باشد وابستگی‌های زیر را اعلام کنید:

dependencies {
    implementation 'io.grpc:grpc-android:1.12.0'
    implementation 'io.grpc:grpc-okhttp:1.12.0'
}

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

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

-dontwarn com.google.**
-dontwarn io.grpc.**
-dontwarn okio.**

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

SDK را راه اندازی کنید

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

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

  1. یک شی 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;
          }
        }
    );
    
  2. یک شی DriverContext ایجاد کنید و فیلدهای مورد نیاز را پر کنید.

    DriverContext driverContext = DriverContext.builder(application)
        .setProviderId(providerId)
        .setVehicleId(vehicleId)
        .setAuthTokenFactory(authTokenFactory)
        .setNavigator(navigator)
        .setRoadSnappedLocationProvider(
            NavigationApi.getRoadSnappedLocationProvider(application))
        .build();
    
  3. از شی DriverContext برای مقداردهی اولیه *DriverApi استفاده کنید.

    DeliveryDriverApi driverApi = DeliveryDriverApi.createInstance(driverContext);
    
  4. DeliveryVehicleReporter را از شی API دریافت کنید. ( DeliveryVehicleReporter NavigationVehicleReporter را گسترش می دهد.)

    DeliveryVehicleReporter vehicleReporter = driverApi.getDeliveryVehicleReporter();
    

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

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

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

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

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

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

class JsonAuthTokenFactory implements AuthTokenFactory {
  private String vehicleServiceToken;  // 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(vehicleId);
    }
    if (ServiceType.VEHICLE.equals(authTokenContext.getServiceType)) {
      return vehicleServiceToken;
    } else {
      throw new RuntimeException("Unsupported ServiceType: " + authTokenContext.getServiceType());
    }
  }

  private void fetchNewToken(String vehicleId) {
    String url = "https://yourauthserver.example/token/" + vehicleId;

    try (Reader r = new InputStreamReader(new URL(url).openStream())) {
      com.google.gson.JsonObject obj
          = com.google.gson.JsonParser.parseReader(r).getAsJsonObject();
      vehicleServiceToken = obj.get("VehicleServiceToken").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);
    }
  }
}

این پیاده‌سازی خاص از سرویس گیرنده جاوا 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.
  }
}

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

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

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

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

DeliveryVehicleReporter reporter = ...;

reporter.enableLocationTracking();

به‌روزرسانی‌های مکان در صورت امکان در یک بازه زمانی منظم ارسال می‌شوند. هر به روز رسانی مکان همچنین نشان می دهد که وسیله نقلیه آنلاین است.

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

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

وقتی شیفت راننده تمام شد، می‌توانید با تماس با DeliveryVehicleReporter.disableLocationTracking به‌روزرسانی‌های مکان را متوقف کنید.

موارد استفاده مدل مورد اعتماد

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

وسیله نقلیه ایجاد کنید

می توانید یک وسیله نقلیه از Driver SDK ایجاد کنید.

قبل از ایجاد وسیله نقلیه، مطمئن شوید که Delivery Driver API را مقداردهی اولیه کرده اید . شناسه خودرو باید با شناسه وسیله نقلیه و ارائه‌دهنده مورد استفاده در هنگام راه‌اندازی Driver SDK ایجاد شود. سپس خودرو را همانطور که در مثال زیر نشان داده شده است ایجاد کنید:

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
try {
  DeliveryVehicle vehicle = vehicleManager.createVehicle().get();
  // Handle CreateVehicleRequest DeliveryVehicle response.
} catch (Exception e) {
  // Handle CreateVehicleRequest error.
}

یک وظیفه تحویل محموله ایجاد کنید

می‌توانید از Driver SDK یک وظیفه تحویل محموله ایجاد کنید.

قبل از ایجاد یک کار، مطمئن شوید که API درایور تحویل را مقداردهی اولیه کرده اید . کار باید با استفاده از شناسه ارائه دهنده مشخص شده در هنگام راه اندازی Driver SDK ایجاد شود. سپس وظیفه تحویل محموله را همانطور که در مثال زیر نشان داده شده است ایجاد کنید. برای اطلاعات در مورد شناسه کار، به مثال‌های شناسه کار مراجعه کنید.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_PICKUP)
   .build();

try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

یک وظیفه تحویل محموله ایجاد کنید

می توانید از Driver SDK یک وظیفه تحویل محموله ایجاد کنید.

قبل از ایجاد یک کار، مطمئن شوید که API درایور تحویل را مقداردهی اولیه کرده اید . سپس وظیفه تحویل محموله را همانطور که در مثال زیر نشان داده شده است ایجاد کنید. برای اطلاعات در مورد شناسه کار، به مثال‌های شناسه کار مراجعه کنید.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
   .setTaskDurationSeconds(2 * 60)
   .setParentId("my-tracking-id")
   .setTaskType(TaskType.DELIVERY_DELIVERY)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

در دسترس نبودن برنامه ریزی شده

می‌توانید از Driver SDK، وظیفه‌ای ایجاد کنید که در دسترس نبودن (مثلاً برای استراحت راننده یا سوخت‌گیری خودرو) باشد. یک کار در دسترس نبودن برنامه ریزی شده نباید شامل شناسه ردیابی باشد. شما می توانید به صورت اختیاری یک مکان ارائه دهید.

قبل از ایجاد یک کار، مطمئن شوید که API درایور تحویل را مقداردهی اولیه کرده اید . سپس وظیفه unavailability را همانطور که در مثال زیر نشان داده شده است ایجاد کنید. برای اطلاعات در مورد شناسه کار، به مثال‌های شناسه کار مراجعه کنید.

static final String TASK_ID = "task-8241890"; // Avoid auto-incrementing IDs.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
   .setTaskDurationSeconds(2 * 60) // Duration or location (or both) must be provided for a BREAK task.
   .setTaskType(TaskType.UNAVAILABLE)
   .build();
try {
   DeliveryTask task = taskManager.createTask(request).get();
   // Handle CreateTaskRequest DeliveryTask response.
} catch (Exception e)  {
   // Handle CreateTaskRequest error.
}

توقف های برنامه ریزی شده

می توانید یک کار توقف برنامه ریزی شده را از Driver SDK ایجاد کنید. یک کار توقف برنامه ریزی شده ممکن است شامل شناسه ردیابی نباشد.

قبل از ایجاد یک کار، مطمئن شوید که API درایور تحویل را مقداردهی اولیه کرده اید . سپس مطابق مثال زیر، وظیفه توقف برنامه ریزی شده را ایجاد کنید. برای اطلاعات در مورد شناسه کار، به مثال‌های شناسه کار مراجعه کنید.

    static final String TASK_ID = "task-8241890"; //  Avoid auto-incrementing IDs.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryTaskManager taskManager = api.getDeliveryTaskManager();
    CreateDeliveryTaskRequest request = CreateDeliveryTaskRequest.builder(TASK_ID)
       .setPlannedWaypoint(Waypoint.builder().setLatLng(-6.195139, 106.820826).build())
       .setTaskDurationSeconds(2 * 60)
       .setTaskType(TaskType.DELIVERY_SCHEDULED_STOP)
       .build();
    try {
       DeliveryTask task = taskManager.createTask(request).get();
       // Handle CreateTaskRequest DeliveryTask response.
    } catch (Exception e)  {
       // Handle CreateTaskRequest error.
    }

به روز رسانی سفارش کار

می توانید ترتیب اجرای وظایف محول شده به وسیله نقلیه را از Driver SDK به روز کنید.

به‌روزرسانی ترتیب کارها، اگر قبلاً به وسیله نقلیه تعیین نشده بود، وظایفی را به وسیله نقلیه اختصاص می‌دهد. همچنین وظایفی را که قبلاً به یک وسیله نقلیه اختصاص داده شده بودند و از ترتیب به‌روزرسانی‌شده خارج شده بودند، می‌بندد. تخصیص یک کار به وسیله نقلیه دیگری در صورتی که قبلاً به وسیله نقلیه دیگری اختصاص داده شده بود خطا ایجاد می کند. قبل از اختصاص دادن یک کار به وسیله نقلیه جدید، کار موجود را ببندید و سپس یک کار جدید ایجاد کنید.

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

قبل از به‌روزرسانی سفارش کار برای یک وسیله نقلیه، مطمئن شوید که وسیله نقلیه و وظایف قبلاً در Fleet Engine ایجاد شده‌اند. سپس دستور کار برای وسیله نقلیه را همانطور که در مثال زیر نشان داده شده است به روز کنید.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    try {
       List<VehicleStop> stops = reporter.setVehicleStops(
         ImmutableList.of(
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.ARRIVED)
                 .setWaypoint(Waypoint.builder().setLatLng(37.1749, 122.412).build())
                 .setTasks(ImmutableList.of(task1)) // Previously created DeliveryTask in Fleet Engine.
                 .build(),
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.NEW) // The current vehicle stop.
                 .setWaypoint(Waypoint.builder().setLatLng(37.7749, 122.4194).build())
                 .setTasks(ImmutableList.of(task2)) // Previously created DeliveryTask in Fleet Engine.
                 .build(),
             VehicleStop.builder()
                 .setVehicleStopState(VehicleStopState.NEW)
                 .setWaypoint(Waypoint.builder().setLatLng(37.3382, 121.8863).build())
                 .setTasks(ImmutableList.of(task3, task4)) // Previously created DeliveryTasks in Fleet Engine.
                 .build())).get();
       // Successfully updated vehicle stops in Fleet Engine. Returns the successfully set VehicleStops.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Setting VehicleStops must be attempted again after resolving
       // errors.
    }

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

مشکلات بالقوه می تواند شامل موارد زیر باشد:

  • VehicleStops مشخص شده از یک الگوی معتبر پیروی نمی کند. فقط اولین VehicleStop می تواند در هر یک از VehicleStopStates باشد: NEW، ENROUTE، یا ARRIVED. VehicleStops بعد از توقف فعلی باید در NEW VehicleStopState باشد.

  • وظایف یا وجود ندارند، یا به وسیله نقلیه دیگری تعلق دارند.

  • وسیله نقلیه وجود ندارد

خودرو به سمت ایستگاه بعدی در حرکت است

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

قبل از اطلاع به Fleet Engine مبنی بر خروج وسیله نقلیه از یک توقف، مطمئن شوید که ایست خودرو ایجاد و تنظیم شده است. سپس همانطور که در مثال زیر نشان داده شده است، حرکت خودرو را به Fleet Engine اطلاع دهید.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    reporter.enableLocationTracking(); // Location tracking must be enabled.

    // Create Vehicle, VehicleStops, and DeliveryTasks.
    // Set VehicleStops on Vehicle.

    navigator.setDestination(vehicleStop.getWaypoint());
    try {
       List<VehicleStop> updatedStops = reporter.enrouteToNextStop().get();
       // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
       // VehicleStop updated to ENROUTE state.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
       // after resolving errors.
    }

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

مشکلات بالقوه می تواند شامل موارد زیر باشد:

  • هیچ توقف VehicleStops در Driver SDK تنظیم نشده است.

خودرو به یک ایستگاه می رسد

هنگام رسیدن وسیله نقلیه به ایستگاه باید به موتور ناوگان اطلاع داده شود. می توانید Fleet Engine را از Driver SDK مطلع کنید.

قبل از اینکه به Fleet Engine اطلاع دهید که وسیله نقلیه به یک ایستگاه رسیده است، مطمئن شوید که توقف خودرو تنظیم شده است. سپس همانطور که در مثال زیر نشان داده شده است، ورود خودرو به ایستگاه را به Fleet Engine اطلاع دهید.

DeliveryDriverApi api = DeliveryDriverApi.getInstance();
DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
reporter.enableLocationTracking(); // Location tracking must be enabled.

// Create Vehicle, VehicleStops, and DeliveryTasks.
// Set VehicleStops on Vehicle.
// Mark ENROUTE to VehicleStop and start guidance using Navigator.

try {
   List<VehicleStop> updatedStopsArrived = reporter.arrivedAtStop().get();
   // Successfully updated vehicle stops in Fleet Engine. Returns the set VehicleStops, with the first
   // VehicleStop updated to ARRIVED state.
   navigator.clearDestinations();
} catch (Exception e)  {
   // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
   // after resolving errors.
}

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

مشکلات احتمالی ممکن است شامل موارد زیر باشد:

  • هیچ توقف VehicleStops در Driver SDK تنظیم نشده است.

خودرو توقف کامل می کند

وقتی خودرویی توقف کامل می کند، باید به Fleet Engine اطلاع دهید. این اعلان باعث می شود که تمام وظایف مرتبط با توقف در حالت بسته قرار گیرند. می توانید Fleet Engine را از Driver SDK مطلع کنید.

همانطور که در مثال زیر نشان داده شده است به Fleet Engine اطلاع دهید که وسیله نقلیه VehicleStop خود را تکمیل کرده است.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleReporter reporter = api.getDeliveryVehicleReporter();
    reporter.enableLocationTracking(); // Location tracking must be enabled.

    // After completing the tasks at the VehicleStop, remove it from the
    // the current list of VehicleStops.

    try {
       List<VehicleStop> updatedStopsCompleted = reporter.completedStop().get();
       // Successfully updated vehicle stops in Fleet Engine. All tasks on the completed stop are set to CLOSED.
       // Returns the set VehicleStops, with the completed VehicleStop removed from the remaining list.
    } catch (Exception e)  {
       // Failed to update vehicle stops in Fleet Engine. Updating VehicleStops must be attempted again
       // after resolving errors.
    }

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

مشکلات بالقوه می تواند شامل موارد زیر باشد:

  • هیچ توقف VehicleStops در Driver SDK تنظیم نشده است.

یک کار را ببندید

برای بستن کاری که به یک وسیله نقلیه محول شده است، یا به Fleet Engine اطلاع دهید که وسیله نقلیه توقفی را که در آن کار انجام می‌شود کامل کرده است، یا آن را از لیست توقف‌های خودرو حذف کنید. برای انجام این کار، می‌توانید فهرست توقف‌های باقی‌مانده وسیله نقلیه را درست مانند زمان به‌روزرسانی سفارش کار برای یک وسیله نقلیه تنظیم کنید.

اگر به یک کار هنوز وسیله نقلیه اختصاص داده نشده است، و باید بسته شود، کار را به حالت بسته به‌روزرسانی کنید. با این حال، نمی‌توانید یک کار بسته را دوباره باز کنید.

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

برای اینکه بتوانید از Driver SDK برای بستن کار استفاده کنید باید یک کار به وسیله نقلیه اختصاص داده شود. برای بستن کاری که به یک وسیله نقلیه محول شده است، به Fleet Engine اطلاع دهید که وسیله نقلیه توقفی را که در آن کار انجام می شود تکمیل کرده است.

از طرف دیگر، ترتیب وظایف وسیله نقلیه ای را که کار به آن محول شده است به روز کنید و سپس کار را از لیست توقف ها حذف کنید.

نتیجه کار و مکان نتیجه را تنظیم کنید

بستن یک کار به معنای موفقیت یا شکست نیست. این نشان می دهد که کار دیگر در حال انجام نیست. برای ردیابی حمل و نقل، مهم است که نتیجه واقعی یک کار را مشخص کنید تا بتوان نتیجه تحویل را نشان داد و صورت‌حساب مناسبی برای خدمات وجود داشت. پس از تنظیم، نمی توانید نتیجه کار را تغییر دهید. اما می توانید زمان نتیجه کار و مکان نتیجه کار را پس از تنظیم آنها تغییر دهید.

کارهایی که در حالت بسته هستند، می‌توانند نتیجه آن‌ها را با موفقیت یا FAILED تنظیم کنند. Fleet Engine فقط وظایف تحویل را با وضعیت SUCCEEDED شارژ می کند.

هنگام علامت گذاری نتیجه یک کار، Fleet Engine به طور خودکار مکان نتیجه کار را با آخرین مکان شناخته شده وسیله نقلیه پر می کند. شما می توانید این رفتار را نادیده بگیرید.

مثال زیر به شما نشان می دهد که چگونه از Driver SDK برای تنظیم نتیجه کار و مهر زمانی استفاده کنید. با استفاده از Driver SDK نمی توانید مکان نتیجه کار را تنظیم کنید.

    static final String TASK_ID = "task-8241890";

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryTaskManager taskManager = api.getDeliveryTaskManager();

    // Updating an existing DeliveryTask which is already CLOSED. Manually
    // setting TaskOutcomeLocation with Driver SDK is not supported at this time.
    UpdateDeliveryTaskRequest req = UpdateDeliveryTaskRequest.builder(TASK_ID)
        .setTaskOutcome(TaskOutcome.SUCCEEDED)
        .setTaskOutcomeTimestamp(now()) // Timestamp in milliseconds.
        .build();

    try {
       DeliveryTask updatedTask = taskManager.updateTask(req);
       // Handle UpdateTaskRequest DeliveryTask response.
    } catch (Exception e)  {
       // Handle UpdateTaskRequest error.
    }

یک وسیله نقلیه را جستجو کنید

می‌توانید یک وسیله نقلیه را از Driver SDK جستجو کنید. قبل از جستجوی یک وسیله نقلیه، مطمئن شوید که Delivery Driver API را راه اندازی کرده اید. سپس می توانید همانطور که در مثال زیر نشان داده شده است، خودرو را جستجو کنید.

    DeliveryDriverApi api = DeliveryDriverApi.getInstance();
    DeliveryVehicleManager vehicleManager = api.getDeliveryVehicleManager();
    try {
       DeliveryVehicle vehicle = vehicleManager.getVehicle().get();
       // Handle GetVehicleRequest DeliveryVehicle response.
    } catch (Exception e)  {
       // Handle GetVehicleRequest error.
    }

DeliveryVehicleManager فقط می تواند DeliveryVehicle برای شناسه وسیله نقلیه ای که در زمان اولیه سازی API Delivery Driver ارائه شده است، جستجو کند.