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

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

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

सिस्टम के लिए ज़रूरी शर्तें

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

Maven कॉन्फ़िगरेशन

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

ग्रेडल

अपनी build.gradle फ़ाइल में ये चीज़ें जोड़ें:

repositories {
    ...
    google()
}

Maven

अपनी pom.xml फ़ाइल में ये चीज़ें जोड़ें:

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

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

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

Consumer 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 शामिल होते हैं. अपने ऐप्लिकेशन में 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 कॉन्फ़िगरेशन में यह डिपेंडेंसी जोड़ें. साथ ही, कंज़्यूमर 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>
    

अपने ऐप्लिकेशन में एपीआई पासकोड जोड़ना

अपने ऐप्लिकेशन में Consumer SDK टूल जोड़ने के बाद, अपने ऐप्लिकेशन में एपीआई पासकोड जोड़ें. आपको वही प्रोजेक्ट एपीआई पासकोड इस्तेमाल करना होगा जो आपको डेवलपमेंट प्रोजेक्ट सेट अप करते समय मिला था.

इस सेक्शन में, एपीआई पासकोड को सेव करने का तरीका बताया गया है, ताकि आपका ऐप्लिकेशन इसे ज़्यादा सुरक्षित तरीके से इस्तेमाल कर सके. आपको वर्शन कंट्रोल सिस्टम में एपीआई पासकोड की जांच नहीं करनी चाहिए. इसे 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 टूल, Fleet Engine से संपर्क करने के लिए, ऐप्लिकेशन से मिले JSON वेब टोकन का इस्तेमाल करता है. ज़्यादा जानकारी के लिए, फ़्लीट इंजन की पुष्टि करना और अनुमति देना देखें.

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

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

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

हमारा सुझाव है कि आप कॉलबैक के लिए, लागू की गई कैश मेमोरी में मौजूद ऑथराइज़ेशन टोकन को रीफ़्रेश करें. साथ ही, expiry का समय बीत जाने के बाद ही उसे रीफ़्रेश करें. टोकन जारी करने के एक घंटे के अंदर ही, टोकन जारी करना चाहिए.

ऑथराइज़ेशन टोकन कॉलबैक से यह पता चलता है कि TripService सेवा के लिए, कौनसा सेवा टोकन ज़रूरी है. इससे कॉन्टेक्स्ट के लिए ज़रूरी tripId भी दी गई है.

नीचे दिए गए उदाहरण में, ऑथराइज़ेशन टोकन कॉलबैक को लागू करने का तरीका बताया गया है.

Java

class JsonAuthTokenFactory implements AuthTokenFactory {

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

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

  private CachedToken token;

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

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

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

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

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

    return token;
  }
}

Kotlin

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: CachedToken? = null

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

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

    return token.tokenValue
  }

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

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

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

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

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

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

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

      token.tripId = tripId

      return token
    }
  }
}

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

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

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

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

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

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

Java

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

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

Kotlin

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

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

पसंदीदा रेंडरर पाने का अनुरोध करने के लिए, Maps SDK टूल को शुरू करें

उपभोक्ता SDK v2.0.0, Android v18.1.0 और इसके बाद के वर्शन के लिए Maps SDK टूल पर काम करता है. यह Google Maps के पसंदीदा रेंडरर की जानकारी देने के अनुरोधों पर काम करता है. ज़्यादा जानकारी के लिए, नया मैप रेंडरर(ऑप्ट-इन) देखें.

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>

Consumer SDK शुरू करने से पहले Maps SDK को शुरू करें

अपनी Application या स्टार्ट-अप Activity क्लास में, MapsInitializer.initialize() को कॉल करें और उपभोक्ता SDK टूल शुरू करने से पहले, रेंडर करने वाले अनुरोध के नतीजे का इंतज़ार करें.

java

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

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

          initializeConsumerSdk();
        }
      });
}

Kotlin

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

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

यूज़र इंटरफ़ेस बनाना

अपने ऐप्लिकेशन का यूज़र इंटरफ़ेस बनाने के लिए, ConsumerMapFragment या ConsumerMapView का इस्तेमाल किया जा सकता है. ConsumerMapFragment में Fragment का इस्तेमाल करके, मैप की जानकारी दी जा सकती है, जबकि ConsumerMapView की मदद से View का इस्तेमाल किया जा सकता है. ConsumerMapView और ConsumerMapFragment, दोनों में राइड शेयर करने की सुविधा एक जैसी है. इसलिए, आपके ऐप्लिकेशन के लिए, View या Fragment में से किसी एक को चुना जा सकता है.

API 19 (KitKat) और वेक्टर ड्रॉबल के लिए सहायता जोड़ें

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

Java

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

// ...

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

Kotlin

// ...
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() तरीके से किया जाना चाहिए.

Java

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {

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

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

}

Kotlin

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

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

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

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

getConsumerGoogleMapAsync() को किया जाने वाला कॉल onCreate() का होना चाहिए. कॉलबैक पैरामीटर के अलावा, इसके लिए ज़रूरी ऐक्टिविटी या फ़्रैगमेंट और GoogleMapOptions (जो शून्य हो सकते हैं) की ज़रूरत होती है, जिनमें MapView के लिए कॉन्फ़िगरेशन एट्रिब्यूट होते हैं. ऐक्टिविटी या फ़्रैगमेंट बेस क्लास, या तो FragmentActivity या सहायता Fragment होनी चाहिए (क्रमश:), क्योंकि उनसे अपने लाइफ़साइकल का ऐक्सेस मिलता है.

Java

public class SampleAppActivity extends AppCompatActivity {

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

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

}

Kotlin

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

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

फ़्रैगमेंट में मौजूद MapView, किसी ऐक्टिविटी में MapView के जैसा ही होता है. हालांकि, इसमें फ़्रैगमेंट उस लेआउट को इनफ़्लेट करता है जिसमें फ़्रैगमेंट onCreateView() तरीके में MapView शामिल होता है.

Java

public class MapViewInFragment extends Fragment {

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

}

Kotlin

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

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

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

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

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

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

AutoCamera

कैमरा व्यवहार को पसंद के मुताबिक बनाना

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

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

राइडशेयर करने की सुविधा और मैप ऐक्सेस करें

अपने ऐप्लिकेशन में राइडशेयर करने और मैप इंटरैक्शन की सुविधा देने के लिए, आपके पास ConsumerGoogleMap और ConsumerController का ऐक्सेस होना चाहिए. ConsumerMapFragment और ConsumerMapView, दोनों ConsumerMapReadyCallback में ConsumerGoogleMap को एसिंक्रोनस तरीके से दिखाते हैं. ConsumerGoogleMap की वजह से, getConsumerController() से ConsumerController की कीमत दिखाई गई है. ConsumerGoogleMap और ConsumerController को इस तरह से ऐक्सेस किया जा सकता है.

Java

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

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

Kotlin

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

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

ConsumerGoogleMap

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

ConsumerController

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

'गतिविधि शेयर करना' सुविधा को सेट अप करें

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

  1. यात्रा के बारे में जानकारी पाने के लिए, TripModel ऑब्जेक्ट पर एक लिसनर रजिस्टर करें. जैसे, ETA (आने का अनुमानित समय) और पहुंचने से पहले वाहन को कितनी दूरी तय करनी है.

    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)
    

यात्रा शेयर करना बंद करें

पक्का करें कि ज़रूरत न होने पर आपने 'गतिविधि शेयर करना' बंद कर दिया. जैसे, होस्ट की गतिविधि खत्म होने पर. 'यात्रा शेयर करना' बंद करने से, Fleet Engine को नेटवर्क के अनुरोध भी बंद हो जाते हैं और मेमोरी लीक होने से बचा जा सकता है.

नीचे दिए गए सैंपल कोड में बताया गया है कि 'गतिविधि के साथ शेयर करना' सुविधा को कैसे बंद किया जाए.

Java

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

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

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

Kotlin

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

यात्रा से जुड़ी गड़बड़ियां ठीक करना

onTripRefreshError तरीके से, यात्रा को मॉनिटर करने के दौरान होने वाली गड़बड़ियों का पता चलता है. उपभोक्ता SDK टूल की गड़बड़ियों की मैपिंग, उन एचटीटीपी/आरपीसी दिशा-निर्देशों का पालन करती है जो 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 टोकन अमान्य हो, क्लाइंट के पास अनुमति न हो या क्लाइंट प्रोजेक्ट के लिए एपीआई चालू न हो. शायद JWT टोकन मौजूद नहीं है या टोकन को किसी ऐसे यात्रा आईडी से साइन किया गया है जो अनुरोध किए गए यात्रा आईडी से मेल नहीं खाती.
429 RESOURCE_EXHAUSTED रिसॉर्स कोटा शून्य है या ट्रैफ़िक की दर तय सीमा से ज़्यादा है.
503 हवा की क्वालिटी की जानकारी उपलब्ध नहीं है सेवा उपलब्ध नहीं है. आम तौर पर, सर्वर काम नहीं करता है.
504 DEADLINE_EXCEEDED अनुरोध की समयसीमा खत्म हो गई है. ऐसा सिर्फ़ तब होगा, जब कॉल करने वाला कोई समयसीमा तय करे जो उसके लिए तय की गई डिफ़ॉल्ट समयसीमा से कम हो.जैसे, अनुरोध को पूरा करने के लिए, अनुरोध की गई समयसीमा काफ़ी नहीं होती. साथ ही, अनुरोध को तय समयसीमा के अंदर पूरा नहीं किया जा सकता.

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