Android के लिए उपभोक्ता SDK का इस्तेमाल शुरू करना

उपभोक्ता SDK टूल का इस्तेमाल, बेसिक उपभोक्ता ऐप्लिकेशन बनाने और उसे चलाने के लिए किया जा सकता है. इस ऐप्लिकेशन को मांग पर राइड और डिलीवरी की सुविधा की बैकएंड सेवाओं के साथ इंटिग्रेट किया गया है. आपके पास यात्रा और ऑर्डर की स्थिति बताने वाला ऐसा ऐप्लिकेशन बनाने की सुविधा होती है जो चालू यात्रा दिखा सकता है, यात्रा के अपडेट का जवाब दे सकता है, और यात्रा की गड़बड़ियों को ठीक कर सकता है.

उपभोक्ता SDK टूल में एक मॉड्यूलर आर्किटेक्चर होता है. इसलिए, आपको एपीआई के उन हिस्सों का इस्तेमाल करना होगा जिन्हें आपको अपने ऐप्लिकेशन के लिए इस्तेमाल करना है. साथ ही, उन्हें अपने एपीआई, Fleet इंजन से मिलने वाली बैकएंड सेवाओं, और Google Maps Platform के एपीआई को जोड़ने की सुविधा भी मिलती है.

सिस्टम में कम से कम यह कॉन्फ़िगरेशन होना चाहिए

यह ज़रूरी है कि मोबाइल डिवाइस, Android 6.0 (एपीआई लेवल 23) या उसके बाद के वर्शन पर काम करता हो.

बिल्ड और डिपेंडेंसी का कॉन्फ़िगरेशन

Google Maven रिपॉज़िटरी का इस्तेमाल करके, उपभोक्ता SDK टूल के 1.99.0 और इसके बाद के वर्शन उपलब्ध कराए गए हैं. डेटा स्टोर करने की निजी जगह का पहले इस्तेमाल किया गया चैनल अब काम नहीं करता.

repositories {
    ...
    google()
}

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

प्रोजेक्ट कॉन्फ़िगरेशन

Android के लिए उपभोक्ता SDK टूल का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को minSdkVersion 23 या उसके बाद के वर्शन को टारगेट करना होगा.

'उपभोक्ता SDK' के साथ बनाए गए ऐप्लिकेशन को चलाने के लिए, Android डिवाइस पर Google Play services इंस्टॉल होना ज़रूरी है.

अपना डेवलपमेंट प्रोजेक्ट सेट अप करें

Google Cloud Console पर अपना डेवलपमेंट प्रोजेक्ट सेट अप करने और प्रोजेक्ट के लिए एपीआई पासकोड पाने के लिए:

1. 'उपभोक्ता SDK' के साथ इस्तेमाल करने के लिए, एक नया Google Cloud Console प्रोजेक्ट बनाएं या कोई मौजूदा प्रोजेक्ट चुनें. कुछ मिनट इंतज़ार करें, जब तक कि Google Cloud Console पर नया प्रोजेक्ट न दिखने लगे.

2. डेमो ऐप्लिकेशन चलाने के लिए, आपके प्रोजेक्ट के पास Android के लिए Maps SDK का ऐक्सेस होना चाहिए. Google Cloud Console में, एपीआई और सेवाएं > लाइब्रेरी चुनें. इसके बाद, Android के लिए Maps SDK टूल खोजें और उसे चालू करें.

3. एपीआई और सेवाएं > क्रेडेंशियल > क्रेडेंशियल बनाएं > एपीआई पासकोड को चुनकर, प्रोजेक्ट के लिए एपीआई पासकोड पाएं. एपीआई पासकोड पाने के बारे में ज़्यादा जानकारी के लिए, एपीआई पासकोड पाना देखें.

अपने ऐप्लिकेशन में उपभोक्ता SDK टूल जोड़ना

उपभोक्ता SDK टूल, Maven का एक निजी डेटा स्टोर करने की जगह पर उपलब्ध है. डेटा स्टोर करने की जगह में SDK टूल के प्रोजेक्ट ऑब्जेक्ट मॉडल (.pom) फ़ाइलें और Javadocs शामिल हैं. अपने ऐप्लिकेशन में उपभोक्ता 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 कॉन्फ़िगरेशन में, इन डिपेंडेंसी जोड़ें. कंज़्यूमर SDK टूल के मनचाहे वर्शन के लिए, VERSION_NUMBER प्लेसहोल्डर को बदलें.

   ग्रेडल

   अपने 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>
   

3. उपभोक्ता SDK टूल, Maps SDK टूल पर निर्भर करता है. यह डिपेंडेंसी इस तरह से कॉन्फ़िगर की गई है कि अगर बिल्ड कॉन्फ़िगरेशन वाली फ़ाइल में Maps SDK के वर्शन को नीचे दी गई फ़ाइल की तरह साफ़ तौर पर तय नहीं किया गया है, तो Maps SDK का नया वर्शन रिलीज़ होने पर, उपभोक्ता SDK टूल उस वर्शन का इस्तेमाल करता रहेगा जो उसके लिए Maps SDK के ज़रूरी वर्शन के साथ काम करता है.

   ग्रेडल

   अपने 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 टूल जोड़ने के बाद, अपने ऐप्लिकेशन में एपीआई पासकोड जोड़ें. आपको उस प्रोजेक्ट API पासकोड का इस्तेमाल करना होगा जो आपको अपना डेवलपमेंट प्रोजेक्ट सेट अप करते समय मिला था.

इस सेक्शन में, एपीआई पासकोड को सेव करने का तरीका बताया गया है, ताकि आपका ऐप्लिकेशन उसे ज़्यादा सुरक्षित तरीके से इस्तेमाल कर सके. आपको अपने वर्शन कंट्रोल सिस्टम में एपीआई पासकोड नहीं देखना चाहिए. इसे local.properties फ़ाइल में सेव किया जाना चाहिए, जो आपके प्रोजेक्ट की रूट डायरेक्ट्री में मौजूद होती है. local.properties फ़ाइल के बारे में ज़्यादा जानकारी के लिए, Gradle प्रॉपर्टी फ़ाइलें देखें.

इस टास्क को व्यवस्थित करने के लिए, Android के लिए सीक्रेट ग्रेडल प्लगिन का इस्तेमाल किया जा सकता है.

प्लग इन इंस्टॉल करने और अपनी एपीआई कुंजी सेव करने के लिए:

1. अपनी रूट-लेवल build.gradle फ़ाइल खोलें और buildscript में मौजूद dependencies एलिमेंट में यहां दिया गया कोड जोड़ें.

   ग्रूवी

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

2. अपनी ऐप्लिकेशन-लेवल build.gradle फ़ाइल खोलें और इस कोड को plugins एलिमेंट में जोड़ें.

   ग्रूवी

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

   Kotlin

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

3. अगर Android Studio का इस्तेमाल किया जा रहा है, तो अपने प्रोजेक्ट को Gradle के साथ सिंक करें.

4. local.properties को अपनी प्रोजेक्ट लेवल की डायरेक्ट्री में खोलें. इसके बाद, यहां दिया गया कोड जोड़ें. 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>

अपने ऐप्लिकेशन में ज़रूरी एट्रिब्यूशन शामिल करना

अगर आपके ऐप्लिकेशन में कंज़्यूमर SDK टूल का इस्तेमाल किया जाता है, तो आपको अपने ऐप्लिकेशन के कानूनी नोटिस वाले सेक्शन में, एट्रिब्यूशन टेक्स्ट और ओपन सोर्स लाइसेंस शामिल करने होंगे. एट्रिब्यूशन को एक इंडिपेंडेंट मेन्यू आइटम या इसके बारे में जानकारी मेन्यू आइटम के हिस्से के रूप में शामिल करना सबसे अच्छा होता है.

लाइसेंस की जानकारी, संग्रह से निकाली गई AAR फ़ाइल की "third_party_लाइसेंस.txt" फ़ाइल में देखी जा सकती है.

ओपन सोर्स सूचनाओं को शामिल करने का तरीका जानने के लिए, https://developers.google.com/android/guides/opensource देखें.

उपभोक्ता SDK टूल की पुष्टि करना

कंज़्यूमर SDK टूल, JSON वेब टोकन का इस्तेमाल करके पुष्टि करता है. JSON Web Token (JWT), JSON-बेस ऐक्सेस टोकन होता है. यह किसी सेवा के लिए एक या एक से ज़्यादा दावे करने की सुविधा देता है. उदाहरण के लिए, सर्वर ऐसा टोकन जनरेट कर सकता है जिसमें "एडमिन के तौर पर लॉग इन किया गया" होने का दावा किया गया हो और वह टोकन किसी क्लाइंट को दे दिया गया हो. इसके बाद क्लाइंट उस टोकन का इस्तेमाल यह साबित करने के लिए कर सकता है कि उसने एडमिन के तौर पर लॉग इन किया है.

उपभोक्ता SDK टूल, फ़्लीट इंजन से संपर्क करने के लिए ऐप्लिकेशन से मिले JSON वेब टोकन का इस्तेमाल करता है. ज़्यादा जानकारी के लिए, फ़्लीट इंजन की पुष्टि और अनुमति देखें.

अनुमति वाले टोकन में, टोकन के authorization हेडर में tripid:TRIP_ID दावा शामिल होना चाहिए. इसमें ट्रिप आईडी TRIP_ID होता है. इससे उपभोक्ता SDK टूल को यात्रा की जानकारी का ऐक्सेस मिलता है. इसमें वाहन की स्थिति, रास्ता, और ETA शामिल हैं.

JSON वेब टोकन कॉलबैक

उपभोक्ता SDK टूल, शुरू करने के दौरान ऐप्लिकेशन के साथ एक ऑथराइज़ेशन टोकन कॉलबैक रजिस्टर करता है. SDK टूल, ऐप्लिकेशन को कॉल करके उन सभी नेटवर्क अनुरोधों के लिए टोकन हासिल करता है जिनके लिए अनुमति की ज़रूरत होती है.

हमारा सुझाव है कि कॉलबैक लागू करने की कैश मेमोरी की पुष्टि करने वाले टोकन, 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
    }
  }
}

एपीआई शुरू करें

इन प्रक्रियाओं को अपनाने से पहले, यह मान लिया जाता है कि आपने सही सेवाएं और उपभोक्ता SDK टूल चालू किए हैं.

ConsumerApi इंस्टेंस पाएं

उपभोक्ता SDK टूल का इस्तेमाल करने के लिए, आपके ऐप्लिकेशन को एसिंक्रोनस रूप से ConsumerApi शुरू करना होगा. एपीआई सिंगलटन है. शुरू करने के तरीके में AuthTokenFactory लगता है. फ़ैक्ट्री ज़रूरत पड़ने पर उपयोगकर्ता के लिए नए JWT टोकन जनरेट करती है.

providerId, आपके Google Cloud प्रोजेक्ट का प्रोजेक्ट आईडी है. प्रोजेक्ट बनाने के बारे में ज़्यादा जानकारी के लिए, Fleet Engine इस्तेमाल करने के लिए गाइड देखें.

आपके ऐप्लिकेशन को कंज़्यूमर SDK टूल की पुष्टि में बताए गए तरीके के मुताबिक AuthTokenFactory लागू करना चाहिए.

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 टूल और मैप रेंडरर

उपभोक्ता SDK v2.x.x, Android v18.1.0 और इसके बाद के वर्शन के लिए Maps SDK पर काम करता है. यहां दी गई टेबल में, Maps के SDK टूल के वर्शन के हिसाब से, डिफ़ॉल्ट रेंडरर की जानकारी दी गई है. साथ ही, यह भी बताया गया है कि दोनों रेंडरर पर क्या काम किया जा सकता है. हमारा सुझाव है कि आप सबसे नए रेंडरर का इस्तेमाल करें. अगर आपको लेगसी रेंडरर का इस्तेमाल करना है, तो MapsInitializer.initialize() का इस्तेमाल करके इसकी जानकारी दें.

* नए मैप रेंडरर के रोल आउट होने पर, सबसे नया रेंडरर डिफ़ॉल्ट हो जाएगा.

Maps SDK को डिपेंडेंसी के तौर पर जोड़ें

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

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

उपभोक्ता के लिए SDK टूल शुरू करने से पहले, Maps SDK टूल चालू करें

अपनी Application या स्टार्ट-अप Activity क्लास में, MapsInitializer.initialize() को कॉल करें. इसके बाद, उपभोक्ता 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) और वेक्टर ड्रॉएबल के लिए सहायता जोड़ें

अगर आपके ऐप्लिकेशन डिज़ाइन को एपीआई 19 (KitKat) वाले डिवाइसों और वेक्टर ड्रॉएबल के साथ काम करने की ज़रूरत है, तो अपनी गतिविधि में यह कोड जोड़ें. इस कोड की वैल्यू AppCompatActivity में दी गई है, ताकि कंज़्यूमर SDK टूल में वेक्टर ड्रॉएबल का इस्तेमाल किया जा सके.

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

// ...

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

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

// ...

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

मैप का हिस्सा या व्यू जोड़ें

किसी Android फ़्रैगमेंट या व्यू में, सफ़र की जानकारी शेयर करने के लिए मैप बनाया जा सकता है, जिसे आपने ऐप्लिकेशन लेआउट की एक्सएमएल फ़ाइल (/res/layout में मौजूद) में तय किया है. इसके बाद, फ़्रैगमेंट (या व्यू), यात्रा की जानकारी शेयर करने वाले मैप का ऐक्सेस देता है, जिसे आपका ऐप्लिकेशन ऐक्सेस कर सकता है और उसमें बदलाव कर सकता है. मैप में, ConsumerController का हैंडल भी उपलब्ध होता है. इससे आपका ऐप्लिकेशन, गतिविधि शेयर करने के अनुभव को कंट्रोल कर सकता है और उसे पसंद के मुताबिक बना सकता है.

सफ़र की जानकारी का मैप और कंट्रोलर शेयर करने की सुविधा

'यात्रा की जानकारी शेयर करने वाला मैप', फ़्रैगमेंट के तौर पर (ConsumerMapFragment का इस्तेमाल करके) या व्यू के तौर पर (ConsumerMapView का इस्तेमाल करके) तय किया जाता है, जैसा कि यहां दिए गए कोड के उदाहरण में दिखाया गया है. इसके बाद, आपके onCreate() वाले तरीके को getConsumerGoogleMapAsync(callback) को कॉल करना चाहिए, जो कॉलबैक में एसिंक्रोनस तरीके से ConsumerGoogleMap दिखाता है. इसके बाद, यात्रा शेयर करने की जानकारी दिखाने के लिए ConsumerGoogleMap का इस्तेमाल किया जाता है. आपके ऐप्लिकेशन के हिसाब से, इसे अपडेट किया जा सकता है.

ConsumerMapFragment

नीचे दिए गए कोड के उदाहरण में बताए गए तरीके की मदद से, आपने अपने ऐप्लिकेशन की लेआउट एक्सएमएल फ़ाइल में फ़्रैगमेंट तय किया है.

<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

इस व्यू को फ़्रैगमेंट या किसी गतिविधि में इस्तेमाल किया जा सकता है, जैसा कि आपकी एक्सएमएल फ़ाइल में तय किया गया है.

<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() से होना चाहिए. कॉलबैक पैरामीटर के जोड़ने के लिए, इसके लिए गतिविधि या फ़्रैगमेंट शामिल होना ज़रूरी है. साथ ही, MapView के लिए कॉन्फ़िगरेशन एट्रिब्यूट वाले GoogleMapOptions (जो शून्य हो सकते हैं) की ज़रूरत होती है. ऐक्टिविटी या फ़्रैगमेंट बेस क्लास 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 के लिए ऊपर दिए गए उदाहरण की तरह ही होता है. हालांकि, फ़्रैगमेंट उस लेआउट को बढ़ा देता है जिसमें फ़्रैगमेंट onCreateView() तरीके में MapView शामिल है.

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

यात्रा पर फ़ोकस करने के लिए, कैमरे के ज़ूम को अडजस्ट किया जा रहा है

Maps SDK टूल में पहले से मौजूद डिफ़ॉल्ट 'मेरी जगह' बटन, कैमरे को डिवाइस की जगह के बीच में रखता है.

अगर कोई गतिविधि शेयर करने का सेशन चालू है, तो हो सकता है कि कैमरे को डिवाइस की जगह के बजाय, सफ़र पर फ़ोकस करना हो.

पहले से मौजूद Android ऐप्लिकेशन के लिए उपभोक्ता SDK टूल: AutoCamera

डिवाइस की जगह की जानकारी के बजाय सफ़र पर फ़ोकस करने के लिए, उपभोक्ता SDK टूल आपको ऑटोकैमरा की सुविधा देता है. यह सुविधा डिफ़ॉल्ट रूप से चालू होती है. कैमरा ज़ूम करता है, ताकि यात्रा की जानकारी शेयर करने वाले रास्ते और अगली यात्रा के वेपॉइंट पर फ़ोकस किया जा सके.

कैमरे के काम करने के तरीके को पसंद के मुताबिक बनाएं

अगर आपको कैमरे के काम करने के तरीके पर ज़्यादा कंट्रोल चाहिए, तो ConsumerController.setAutoCameraEnabled() का इस्तेमाल करके ऑटो कैमरा को बंद या चालू किया जा सकता है.

ConsumerController.getCameraUpdate(), सुझाए गए कैमरे की बाउंड्री को उस समय दिखाता है. इसके बाद, इस CameraUpdate को GoogleMap.moveCamera() या GoogleMap.animateCamera() में आर्ग्युमेंट के तौर पर जोड़ा जा सकता है.

राइडशेयरिंग और मैप ऐक्सेस करें

अपने ऐप्लिकेशन में राइडशेयरिंग और मैप इंटरैक्शन की सुविधा देने के लिए, आपके पास ConsumerGoogleMap और ConsumerController का ऐक्सेस होना चाहिए. ConsumerMapFragment और ConsumerMapView, दोनों एसिंक्रोनस रूप से ConsumerMapReadyCallback में ConsumerGoogleMap लौटाते हैं. ConsumerGoogleMap, getConsumerController() से ConsumerController दिखाएगा. यहां बताए गए तरीके से, 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 क्लास के लिए एक रैपर क्लास है. इससे आपका ऐप्लिकेशन, GoogleMap के बराबर एपीआई का इस्तेमाल करके, मैप के साथ इंटरैक्ट कर सकता है. उपभोक्ता मैप का इस्तेमाल करने से आपका ऐप्लिकेशन और राइड शेयरिंग एक ही बुनियादी Google Maps के साथ बिना किसी रुकावट के इंटरैक्ट कर सकते हैं. उदाहरण के लिए, GoogleMap सिर्फ़ एक कॉलबैक रजिस्ट्रेशन की अनुमति देता है, लेकिन ConsumerGoogleMap, ड्यूअल रजिस्टर किए गए कॉलबैक के साथ काम करता है. इन कॉलबैक की मदद से, आपका ऐप्लिकेशन और राइड शेयर करने की सुविधा उन कॉलबैक को रजिस्टर करती है जिन्हें एक क्रम में कॉल किया जाता है.

ConsumerController

ConsumerController, राइड शेयर करने की सुविधा देता है. जैसे, यात्राओं की निगरानी करना, यात्रा की स्थिति कंट्रोल करना, और जगह की जानकारी सेट करना.

यात्रा शेयर करने की सुविधा सेट अप करना

जब बैकएंड किसी उपभोक्ता से वाहन में डेटा मैच करता है, तब यात्रा शेयर करने का यूज़र इंटरफ़ेस शुरू करने के लिए JourneySharingSession का इस्तेमाल करें. यात्रा की जानकारी शेयर करने की सुविधा से, मेल खाने वाले वाहन की जगह और रास्ता दिखता है. अपने ऐप्लिकेशन में SDK टूल लागू करने के बाद, यात्राओं की निगरानी करने, अपडेट सुनने, और गड़बड़ियों को ठीक करने के लिए सुविधा जोड़ी जा सकती है. इन प्रक्रियाओं में यह माना जाता है कि बैकएंड सेवाएं लागू हैं और वाहनों से मेल खाने वाले उपभोक्ताओं के लिए आपकी सेवाएं काम कर रही हैं.

1. यात्रा के बारे में जानकारी पाने के लिए, 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?,
       ) {
         // ...
       }
   
     // ...
   })
   

2. 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)
   

यात्रा की जानकारी शेयर करने की सुविधा बंद करना

पक्का करें कि ज़रूरत न होने पर, यात्रा शेयर करने की सुविधा बंद कर दी जाए. जैसे, होस्ट की गतिविधि खत्म होने पर. यात्रा की जानकारी शेयर करने की सुविधा को बंद करने से, फ़्लीट इंजन को नेटवर्क के अनुरोध भी बंद हो जाते हैं. साथ ही, मेमोरी लीक भी नहीं होती.

यहां दिया गया सैंपल कोड, यात्रा की जानकारी शेयर करने की सुविधा को बंद करने का तरीका बताता है.

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 तरीका, यात्रा की निगरानी के दौरान होने वाली गड़बड़ियों को दिखाता है. उपभोक्ता SDK टूल की गड़बड़ियों के लिए मैपिंग, उन एचटीटीपी/RPC दिशा-निर्देशों का पालन करती हैं जो Google Cloud Platform के लिए तय किए गए हैं. यात्रा की निगरानी करते समय दिखने वाली सामान्य गड़बड़ियों में ये शामिल हैं:

ज़्यादा जानकारी के लिए, उपभोक्ता SDK टूल की गड़बड़ी को मैनेज करना लेख पढ़ें.