شروع به کار با Consumer SDK برای Android

می‌توانید از Consumer SDK برای ساخت و اجرای یک برنامه مصرف‌کننده اساسی که با خدمات باطنی Rides و Deliveries Solution بر اساس تقاضا یکپارچه شده است، استفاده کنید. می توانید یک برنامه Trip and Order Progress ایجاد کنید که می تواند یک سفر فعال را نمایش دهد، به به روز رسانی سفر پاسخ دهد و خطاهای سفر را مدیریت کند.

از آنجایی که Consumer SDK یک معماری ماژولار دارد، می‌توانید از بخش‌هایی از API که می‌خواهید برای برنامه خاص خود استفاده کنید استفاده کنید و آنها را با APIهای خود، سرویس‌های Backend ارائه‌شده توسط Fleet Engine و API‌های اضافی پلتفرم نقشه‌های Google ادغام کنید. .

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

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

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

نسخه 1.99.0 و جدیدتر SDK مصرف کننده با استفاده از مخزن 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>

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

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

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

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

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

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

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

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

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

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

  1. همانطور که در بخش قبل توضیح داده شد، محیط خود را برای دسترسی به مخزن میزبان Maven تنظیم کنید.

    اگر پیکربندی مدیریت وابستگی متمرکزی دارید که در settings.gradle اعلام شده است، آن را به صورت زیر غیرفعال کنید.

    • بلوک کد زیر را در settings.gradle حذف کنید:

      import org.gradle.api.initialization.resolve.RepositoriesMode
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

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

    گریدل

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

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

    ماون

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

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

  3. Consumer SDK به Maps SDK بستگی دارد. این وابستگی به گونه ای پیکربندی شده است که اگر نسخه Maps SDK به صراحت در فایل پیکربندی ساخت مانند زیر تعریف نشده باشد ، زمانی که نسخه جدیدی از Maps SDK منتشر شد، SDK مصرف کننده به استفاده از حداقل نسخه Maps SDK پشتیبانی شده ادامه خواهد داد . مورد نیاز آن است.

    گریدل

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

    dependencies {
  ...
  implementation 'com.google.android.gms:play-services-maps:18.1.0'
}

    ماون

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

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

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

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

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

برای ساده‌سازی این کار، می‌توانید از افزونه 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. اگر از Android Studio استفاده می کنید، پروژه خود را با 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.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>

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

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

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

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

احراز هویت SDK مصرف کننده

Consumer SDK با استفاده از JSON Web Tokens احراز هویت را فراهم می کند. JSON Web Token (JWT) یک نشانه دسترسی مبتنی بر JSON است که یک یا چند ادعا را در مورد یک سرویس ارائه می دهد. به عنوان مثال، یک سرور می‌تواند توکنی تولید کند که ادعای «به‌عنوان مدیر وارد شده» باشد و آن را در اختیار مشتری قرار دهد. سپس مشتری می تواند از آن توکن برای اثبات اینکه به عنوان مدیر وارد شده است استفاده کند.

Consumer SDK از JSON Web Token ارائه شده توسط برنامه برای ارتباط با Fleet Engine استفاده می کند. برای اطلاعات بیشتر به احراز هویت و مجوز ناوگان موتور مراجعه کنید.

نشانه مجوز باید شامل یک ادعای tripid:TRIP_ID در سرصفحه authorization رمز باشد، جایی که TRIP_ID شناسه سفر است. این امکان دسترسی Consumer SDK را به جزئیات سفر، از جمله موقعیت وسیله نقلیه، مسیر، و ETA می‌دهد.

پاسخ تماس JSON Web Token

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

اکیداً توصیه می‌کنیم که توکن‌های مجوز اجرای Cache Backback خود را به‌روزرسانی کنید و فقط زمانی که زمان expiry گذشته است، آن‌ها را بازخوانی کنید. توکن ها باید با انقضای یک ساعته صادر شوند.

پاسخ تماس توکن مجوز مشخص می کند که کدام توکن سرویس برای سرویس TripService مورد نیاز است. همچنین tripId مورد نیاز را برای متن فراهم می کند.

مثال کد زیر نشان می دهد که چگونه می توان یک پاسخ تماس توکن مجوز را پیاده سازی کرد.

جاوا

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;
  }
}

کاتلین

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
    }
  }
}

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

قبل از دنبال کردن این مراحل، فرض بر این است که شما خدمات مناسب و Consumer SDK را فعال کرده اید.

نمونه ConsumerApi را دریافت کنید

برای استفاده از Consumer SDK، برنامه شما باید ConsumerApi به صورت ناهمزمان مقداردهی اولیه کند. API یک تکتونه است. روش مقداردهی اولیه یک AuthTokenFactory می گیرد. کارخانه در صورت لزوم توکن های جدید JWT را برای کاربر تولید می کند.

providerId شناسه پروژه Google Cloud Project شما است. برای اطلاعات بیشتر در مورد ایجاد پروژه به راهنمای کاربر Fleet Engine مراجعه کنید.

برنامه شما باید AuthTokenFactory همانطور که در Consumer SDK Authentication توضیح داده شده پیاده سازی کند.

جاوا

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

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

کاتلین

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

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

Maps SDK را برای درخواست ارائه‌دهنده ترجیحی راه‌اندازی کنید

Consumer SDK v2.0.0 از Maps SDK for Android نسخه 18.1.0 و بالاتر پشتیبانی می کند. از درخواست‌هایی پشتیبانی می‌کند که رندر Google Maps ترجیحی را مشخص می‌کنند. برای جزئیات، به New Map Renderer (opt-in) مراجعه کنید.

Maps SDK را به عنوان یک وابستگی اضافه کنید

گریدل

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

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

ماون

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

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

قبل از مقداردهی اولیه SDK مصرف کننده، Maps SDK را مقداردهی کنید

در کلاس Application یا Start-up Activity خود، MapsInitializer.initialize() را فراخوانی کنید و قبل از شروع به کار Consumer SDK منتظر نتیجه درخواست رندر باشید.

جاوا

@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();
        }
      });
}

کاتلین

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 برای برنامه شما بهتر است یکی را انتخاب کنید.

پشتیبانی از API 19 (KitKat) و کشش‌های Vector را اضافه کنید

اگر طراحی برنامه شما نیاز به پشتیبانی از دستگاه‌های API 19 (KitKat) و نقشه‌های برداری دارد، کد زیر را به Activity خود اضافه کنید. این کد AppCompatActivity برای استفاده از ترسیم‌های Vector در Consumer SDK گسترش می‌دهد.

جاوا

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

// ...

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

کاتلین

// ...
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() باشد.

جاوا

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();
            }
          });
    }
  }

}

کاتلین

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 پشتیبانی باشد، زیرا آنها دسترسی به چرخه حیات آن را فراهم می کنند.

جاوا

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);
    }
  }

}

کاتلین

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() افزایش می‌دهد.

جاوا

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);
  }

}

کاتلین

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

تنظیم زوم دوربین برای تمرکز بر یک سفر

دکمه پیش‌فرض My Location که در Maps SDK تعبیه شده است، دوربین را روی مکان دستگاه متمرکز می‌کند.

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

راه حل داخلی SDK مصرف کننده برای Android: AutoCamera

برای اینکه بتوانید به جای مکان دستگاه روی سفر تمرکز کنید، Consumer SDK یک ویژگی AutoCamera را ارائه می دهد که به طور پیش فرض فعال است. دوربین بزرگنمایی می کند تا روی مسیر اشتراک گذاری سفر و ایستگاه بعدی سفر تمرکز کند.

دوربین خودکار

سفارشی کردن رفتار دوربین

اگر به کنترل بیشتری بر رفتار دوربین نیاز دارید، می‌توانید دوربین خودکار را با استفاده از ConsumerController.setAutoCameraEnabled() غیرفعال یا فعال کنید.

ConsumerController.getCameraUpdate() محدوده های توصیه شده دوربین را در آن لحظه برمی گرداند. سپس می توانید این CameraUpdate به عنوان یک آرگومان برای GoogleMap.moveCamera() یا GoogleMap.animateCamera() ارائه دهید.

به اشتراک گذاری سواری و نقشه ها دسترسی داشته باشید

برای پشتیبانی از اشتراک گذاری سواری و تعامل نقشه در برنامه خود، باید به ConsumerGoogleMap و ConsumerController دسترسی داشته باشید. ConsumerMapFragment و ConsumerMapView هر دو به طور ناهمزمان ConsumerGoogleMap در ConsumerMapReadyCallback برمی‌گردانند. ConsumerGoogleMap ConsumerController از getConsumerController() برمی گرداند. به صورت زیر می توانید به ConsumerGoogleMap و ConsumerController دسترسی داشته باشید.

جاوا

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);

کاتلین

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 است. این امکان را برای برنامه شما فراهم می کند تا با استفاده از یک API معادل GoogleMap با نقشه تعامل داشته باشد. استفاده از نقشه مصرف‌کننده به برنامه و اشتراک‌گذاری سواری شما اجازه می‌دهد تا با همان GoogleMap زیربنایی تعامل یکپارچه داشته باشد. به عنوان مثال، GoogleMap تنها امکان ثبت نام پاسخ به تماس را می دهد، اما ConsumerGoogleMap از تماس های ثبت شده دوگانه پشتیبانی می کند. این تماس‌ها به برنامه و اشتراک‌گذاری سواری شما اجازه می‌دهد تا تماس‌هایی را که به‌طور متوالی فراخوانی می‌شوند، ثبت کند.

ConsumerController

ConsumerController دسترسی به قابلیت های اشتراک گذاری سواری مانند نظارت بر سفرها، کنترل وضعیت سفر و تنظیم مکان ها را فراهم می کند.

راه‌اندازی اشتراک‌گذاری سفر

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

  1. یک شنونده را در یک شی TripModel ثبت کنید تا جزئیات سفر مانند ETA (زمان تخمینی رسیدن) و مسافتی که وسیله نقلیه باید قبل از رسیدن طی کند را دریافت کنید.

    جاوا

    // 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) {
    // ...
  }

  // ...
});

    کاتلین

    // 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?,
    ) {
      // ...
    }

  // ...
})

  2. سفر خود را با استفاده از TripModelOptions پیکربندی کنید.

    جاوا

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

    کاتلین

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

اشتراک گذاری سفر را متوقف کنید

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

کد نمونه زیر نحوه توقف اشتراک گذاری سفر را نشان می دهد.

جاوا

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

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

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

کاتلین

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

خطاهای سفر را مدیریت کنید

روش onTripRefreshError خطاهایی را که در حین نظارت بر سفر رخ می دهد را نشان می دهد. نقشه برداری برای خطاهای Consumer SDK از همان دستورالعمل های HTTP/RPC پیروی می کند که برای Google Cloud Platform ایجاد شده است. خطاهای رایجی که در حین نظارت بر سفر ظاهر می شوند عبارتند از:

HTTP RPC شرح
400 INVALID_ARGUMENT مشتری یک نام سفر نامعتبر مشخص کرده است. نام سفر باید از فرمت providers/{provider_id}/trips/{trip_id} پیروی کند. Provider_id باید شناسه پروژه Cloud متعلق به ارائه دهنده خدمات باشد.
401 بدون احراز هویت درخواست به دلیل یک توکن JWT نامعتبر احراز هویت نشد. اگر توکن JWT بدون شناسه سفر امضا شده باشد یا نشانه JWT منقضی شده باشد، این خطا رخ می دهد.
403 PERMISSION_DENIED مشتری مجوز کافی ندارد. اگر توکن JWT نامعتبر باشد، کلاینت مجوز نداشته باشد یا API برای پروژه مشتری فعال نباشد، این خطا رخ می دهد. ممکن است رمز JWT وجود نداشته باشد یا رمز با شناسه سفری امضا شده باشد که با شناسه سفر درخواستی مطابقت ندارد.
429 RESOURCE_EXHAUSTED سهمیه منابع صفر است یا میزان ترافیک از حد مجاز فراتر می رود.
503 غیر قابل دسترسی سرویس در دسترس نیست. به طور معمول سرور از کار افتاده است.
504 DEADLINE_EXCEEDED مهلت درخواست فراتر رفت. این تنها در صورتی اتفاق می‌افتد که تماس‌گیرنده ضرب‌الاجلی کوتاه‌تر از مهلت پیش‌فرض متد تعیین کند (یعنی مهلت درخواستی برای پردازش درخواست توسط سرور کافی نباشد) و درخواست در مهلت تعیین شده به پایان نرسد.

برای اطلاعات بیشتر، به مدیریت خطاهای SDK مصرف کننده مراجعه کنید.