Android için Tüketici SDK'sını Kullanmaya Başlama

İsteğe Bağlı Yolculuklar ve Teslimatlar Çözümü arka uç hizmetleriyle entegre temel bir tüketici uygulaması derleyip çalıştırmak için Tüketici SDK'sını kullanabilirsiniz. Aktif bir geziyi gösterebilen, gezi güncellemelerine yanıt verebilen ve gezi hatalarını işleyebilen bir Seyahat ve Sipariş İlerlemesi uygulaması oluşturabilirsiniz.

Consumer SDK'nın modüler bir mimarisi olduğundan API'nin belirli bir uygulamanız için kullanmak istediğiniz bölümlerini kullanabilir ve bunları kendi API'lerinizle, Fleet Engine tarafından sağlanan arka uç hizmetleriyle ve Google Haritalar Platformu'ndaki ek API'lerle entegre edebilirsiniz.

Minimum sistem gereksinimleri

Mobil cihazda Android 6.0 (API düzeyi 23) veya sonraki sürümler yüklü olmalıdır.

Derleme ve bağımlılık yapılandırması

Tüketici SDK'sı 1.99.0 ve sonraki sürümleri, Google Maven deposu kullanılarak kullanılabilir. Daha önce kullanılan özel depo kanalı kullanımdan kaldırıldı.

repositories {
    ...
    google()
}

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

Proje Yapılandırması

Android için Tüketici SDK'sını kullanmak istiyorsanız uygulamanızın minSdkVersion 23 veya sonraki bir sürümü hedeflemesi gerekir.

Tüketici SDK'sı ile oluşturulmuş bir uygulamayı çalıştırmak için Android cihazda Google Play Hizmetleri yüklü olmalıdır.

Geliştirme projenizi oluşturun

Geliştirme projenizi oluşturmak ve Google Cloud Console'da projenize ait bir API anahtarı almak için:

1. Tüketici SDK'sı ile kullanılacak yeni bir Google Cloud Console projesi oluşturun veya mevcut bir projeyi seçin. Yeni proje Google Cloud Console'da görünene kadar birkaç dakika bekleyin.

2. Demo uygulamayı çalıştırmak istiyorsanız projenizin Android için Haritalar SDK'sına erişimi olmalıdır. Google Cloud Console'da API'ler ve Hizmetler > Kitaplık'ı seçin ve ardından Android için Haritalar SDK'sını bulup etkinleştirin.

3. API'ler ve Hizmetler > Kimlik bilgileri > Kimlik bilgisi oluştur > API anahtarı'nı seçerek proje için bir API anahtarı alın. API anahtarı alma hakkında daha fazla bilgi için API anahtarı alma bölümüne bakın.

Tüketici SDK'sını uygulamanıza ekleyin

Tüketici SDK'sı özel bir Maven deposu üzerinden kullanılabilir. Depo, SDK'nın Proje Nesne Modeli (.pom) dosyalarını ve Javadocs'larını içerir. Tüketici SDK'sını uygulamanıza eklemek için:

1. Ortamınızı, önceki bölümde açıklandığı gibi ana makine Maven deposuna erişecek şekilde ayarlayın.

   settings.gradle içinde beyan edilmiş merkezi bağımlılık yönetimi yapılandırmanızı varsa aşağıdaki şekilde devre dışı bırakın.

   • settings.gradle ürününde aşağıdaki kod bloğunu kaldırın:

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

2. Aşağıdaki bağımlılığı Gradle veya Maven yapılandırmanıza ekleyerek VERSION_NUMBER yer tutucusunu Tüketici SDK'sının istediğiniz sürümü ile değiştirin.

   Gradle

   build.gradle cihazınıza şunları ekleyin:

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

   Maven

   pom.xml cihazınıza şunları ekleyin:

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

3. Tüketici SDK'sı, Haritalar SDK'sına bağlıdır. Bu bağımlılık, Haritalar SDK'sı sürümü derleme yapılandırma dosyasında aşağıdaki gibi açıkça tanımlanmamışsa, Haritalar SDK'sının yeni bir sürümü yayınlandığında, Tüketici SDK'sının gerektirdiği minimum desteklenen Haritalar SDK sürümünü kullanmaya devam edeceği şekilde yapılandırılır.

   Gradle

   build.gradle cihazınıza şunları ekleyin:

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

   Maven

   pom.xml cihazınıza şunları ekleyin:

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

API anahtarını uygulamanıza ekleyin

Tüketici SDK'sını uygulamanıza ekledikten sonra API anahtarını uygulamanıza ekleyin. Geliştirme projenizi oluştururken edindiğiniz proje API anahtarını kullanmanız gerekir.

Bu bölümde, uygulamanız tarafından daha güvenli bir şekilde referans verilebilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize kontrol etmemelisiniz. Projenizin kök dizininde bulunan local.properties dosyasında depolanmalıdır. local.properties dosyası hakkında daha fazla bilgi için Gradle özellikleri dosyaları bölümüne bakın.

Bu görevi kolaylaştırmak için Android için Secrets Gradle Eklentisi'ni kullanabilirsiniz.

Eklentiyi yüklemek ve API anahtarınızı saklamak için:

1. Kök düzeyindeki build.gradle dosyanızı açın ve aşağıdaki kodu buildscript altındaki dependencies öğesine ekleyin.

   Modern

   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. Uygulama düzeyindeki build.gradle dosyanızı açın ve plugins öğesine aşağıdaki kodu ekleyin.

   Modern

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

   Kotlin

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

3. Android Studio kullanıyorsanız projenizi Gradle ile senkronize edin.

4. Proje düzeyindeki dizinde local.properties dosyasını açın ve aşağıdaki kodu ekleyin. YOUR_API_KEY kısmını API anahtarınızla değiştirin.

   MAPS_API_KEY=YOUR_API_KEY
   

5. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY adresine gidin ve android:value özelliğini aşağıdaki şekilde güncelleyin:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
   

Aşağıdaki örnekte, örnek bir uygulama için eksiksiz bir manifest gösterilmektedir:

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

Uygulamanıza gerekli ilişkilendirmeleri dahil edin

Uygulamanızda Tüketici SDK'sını kullanıyorsanız uygulamanızın yasal uyarılar bölümünün bir parçası olarak ilişkilendirme metni ve açık kaynak lisansları eklemeniz gerekir. İlişkilendirmeleri bağımsız bir menü öğesi veya bir Hakkında menü öğesinin parçası olarak eklemek en iyisidir.

Lisans bilgileri, arşivden çıkarılmış AAR dosyasındaki "third_party_LICENSEs.txt" dosyasında bulunabilir.

Açık kaynak bildirimlerini nasıl ekleyeceğinizi öğrenmek için https://developers.google.com/android/guides/opensource adresine bakın.

Tüketici SDK'sı Kimlik Doğrulaması

Tüketici SDK'sı, JSON Web Jetonları kullanarak kimlik doğrulama sağlar. JSON Web Token (JWT), bir hizmette bir veya daha fazla hak talebi sağlayan JSON tabanlı bir erişim jetonudur. Örneğin, bir sunucu "yönetici olarak giriş yapıldı" iddiasını içeren bir jeton oluşturabilir ve bunu istemciye sağlayabilir. Daha sonra istemci, bu jetonu kullanarak hesabın yönetici olarak giriş yaptığını kanıtlayabilir.

Tüketici SDK'sı, Fleet Engine ile iletişim kurmak için uygulama tarafından sağlanan JSON Web Token'ı kullanır. Daha fazla bilgi için Fleet Engine Kimlik Doğrulaması ve Yetkilendirmesi bölümüne bakın.

Yetkilendirme jetonu, jetonun authorization başlığında bir tripid:TRIP_ID talebi içermelidir. Burada TRIP_ID, gezi kimliğidir. Bu sayede Tüketici SDK'sı araç konumu, rota ve TVS gibi gezi ayrıntılarına erişebilir.

JSON Web Jetonu geri çağırmaları

Tüketici SDK'sı, başlatma sırasında uygulamaya bir yetkilendirme jetonu geri çağırması kaydeder. SDK, yetkilendirme gerektiren tüm ağ istekleri için bir jeton almak üzere uygulamayı çağırır.

Geri çağırma uygulamanızın önbellek yetkilendirme jetonlarını kullanmanızı ve bunları yalnızca expiry süresi dolduğunda yenilemenizi önemle tavsiye ederiz. Jetonlar, bir saatlik geçerlilik süresiyle verilmelidir.

Yetkilendirme jetonu geri çağırması, TripService hizmeti için hangi hizmet jetonunun gerekli olduğunu belirtir. Ayrıca bağlam için gerekli tripId değerini de sağlar.

Aşağıdaki kod örneği, yetkilendirme jetonu geri çağırmasının nasıl uygulanacağını gösterir.

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'yi başlatma

Bu prosedürleri uygulamadan önce, uygun hizmetleri ve Tüketici SDK'sını etkinleştirdiğiniz varsayılır.

ConsumerApi örneğini alın

Tüketici SDK'sını kullanmak için uygulamanızın ConsumerApi eşzamansız olarak başlatılması gerekir. API tek bir API'dir. Başlatma yöntemi AuthTokenFactory sürer. Fabrika, gerektiğinde kullanıcı için yeni JWT jetonları oluşturur.

providerId, Google Cloud projenizin proje kimliğidir. Proje oluşturma hakkında daha fazla bilgi için Fleet Engine Kullanıcı Kılavuzu'na bakın.

Uygulamanız, AuthTokenFactory öğesini Tüketici SDK'sı Kimlik Doğrulaması bölümünde açıklandığı şekilde uygulamalıdır.

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
}

Haritalar SDK'sı ve harita oluşturucuları

Tüketici SDK'sı v2.x.x sürümü, Android 18.1.0 ve üzeri sürümler için Haritalar SDK'sını destekler. Aşağıdaki tabloda, Haritalar SDK'sı sürümüne göre varsayılan oluşturucu ve her iki oluşturucunun desteklenebilirliği özetlenmektedir. En son oluşturucuyu kullanmanızı öneririz, ancak eski oluşturucuyu kullanmanız gerekiyorsa MapsInitializer.initialize() kullanarak bunu açıkça belirtebilirsiniz.

* Yeni Haritalar Oluşturucu'nun kullanıma sunulmasıyla birlikte, En son oluşturucu varsayılan olarak kullanılacaktır.

Bağımlılık olarak Haritalar SDK'sı ekleme

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>

Tüketici SDK'sını başlatmadan önce Haritalar SDK'sını başlatın

Application veya başlangıç Activity sınıfınızda, Tüketici SDK'sını başlatmadan önce MapsInitializer.initialize() işlevini çağırın ve oluşturucu istek sonucunu bekleyin.

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

Kullanıcı Arayüzünü Oluşturma

Uygulamanızın kullanıcı arayüzünü oluşturmak için ConsumerMapFragment veya ConsumerMapView kullanabilirsiniz. ConsumerMapFragment, haritanızı Fragment kullanarak tanımlamanıza olanak tanırken ConsumerMapView, View kullanmanıza olanak tanır. Yolculuk paylaşımı işlevi hem ConsumerMapView hem de ConsumerMapFragment ürününde aynıdır. Bu nedenle, View veya Fragment arasından hangisinin daha iyi olduğuna bağlı olarak birini seçebilirsiniz.

API 19 (KitKat) ve Vector çekilebilir öğeleri için destek

Uygulamanızın tasarımı için API 19 (KitKat) cihazlar ve vektör çekilebilir öğeleri için destek gerekiyorsa aşağıdaki kodu Etkinliğinize ekleyin. Bu kodlar, Tüketici SDK'sında Vektör çekilebilir noktalarını kullanmak için AppCompatActivity öğesini genişletir.

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

// ...

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

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

// ...

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

Harita parçasını veya görünümü ekleme

Yolculuk paylaşımını, uygulama düzeni XML dosyanızda (/res/layout içinde bulunur) tanımladığınız bir Android parçası veya görünümde göstermek için harita oluşturursunuz. Parça (veya görünüm), uygulamanızın erişip değiştirebileceği yolculuk paylaşımı haritasına erişim sağlar. Harita, uygulamanızın yolculuk paylaşımı deneyimini kontrol etmesine ve özelleştirmesine olanak tanıyan ConsumerController için bir tutma yeri de sağlar.

Yolculuk paylaşımı haritası ve denetleyici

Aşağıdaki kod örneğinde gösterildiği gibi yolculuk paylaşımı haritasını bir parça (ConsumerMapFragment kullanarak) veya görünüm (ConsumerMapView kullanarak) olarak tanımlarsınız. Bu durumda onCreate() yönteminiz, geri çağırmada eşzamansız olarak ConsumerGoogleMap değeri döndüren getConsumerGoogleMapAsync(callback) yöntemini çağırır. Daha sonra, yolculuk paylaşımını göstermek için ConsumerGoogleMap kullanabilirsiniz. Bu bilgi, uygulamanız tarafından gerektiğinde güncellenebilir.

ConsumerMapFragment

Aşağıdaki kod örneğinde gösterildiği gibi, uygulama düzeni XML dosyanızda parçayı tanımlarsınız.

<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() çağrısı, onCreate() yönteminden gelmelidir.

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

Görünüm, XML dosyanızda tanımlandığı gibi bir parçada veya bir etkinlikte kullanılabilir.

<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() numaralı telefona yapılacak arama onCreate() olacaktır. Geri çağırma parametresine ek olarak, içeren etkinlik veya parça ile GoogleMapOptions (boş olabilir) ve MapView için yapılandırma özelliklerini içerir. Etkinlik veya parça temel sınıfı, kendi yaşam döngüsüne erişim sağladığı için FragmentActivity ya da destek Fragment (sırasıyla) olmalıdır.

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

Bir parçadaki MapView, bir etkinlikteki MapView için yukarıdaki örnekle aynıdır ancak parça, onCreateView() parçası yöntemindeki MapView öğesini içeren düzeni şişirir.

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

Bir yolculuğa odaklanmak için kameranın yakınlaştırmasını ayarlama

Haritalar SDK'sında yerleşik olarak bulunan varsayılan Konumum düğmesi, kamerayı cihaz konumuna göre ortalar.

Etkin bir yolculuk paylaşımı oturumu varsa kamerayı ortalayarak cihazın konumu yerine yolculuğa odaklanmanızı öneririz.

Yerleşik Android çözümü için Tüketici SDK'sı: AutoKamera

Tüketici SDK'sı, cihaz konumu yerine yola odaklanmanız için varsayılan olarak etkinleştirilen bir AutoKamera özelliği sağlar. Kamera, yolculuk paylaşımı rotasına ve sonraki gezi ara noktasına odaklanmak için yakınlaştırılır.

Kamera davranışını özelleştirme

Kamera davranışı üzerinde daha fazla kontrole ihtiyacınız varsa ConsumerController.setAutoCameraEnabled() işlevini kullanarak otomatik kamerayı devre dışı bırakabilir veya etkinleştirebilirsiniz.

ConsumerController.getCameraUpdate(), önerilen kamera sınırlarını döndürür. Daha sonra bu CameraUpdate öğesini, GoogleMap.moveCamera() veya GoogleMap.animateCamera() işlevi için bir bağımsız değişken olarak sağlayabilirsiniz.

Araç paylaşımına ve haritalara erişme

Uygulamanızda araç paylaşımı ve harita etkileşimini desteklemek için ConsumerGoogleMap ve ConsumerController erişiminiz olmalıdır. ConsumerMapFragment ve ConsumerMapView eşzamansız olarak ConsumerGoogleMap değerini ConsumerMapReadyCallback içinde döndürür. ConsumerGoogleMap, getConsumerController() mağazasından ConsumerController tutarında iade yaptı. ConsumerGoogleMap ve ConsumerController hizmetlerine aşağıdaki şekilde erişebilirsiniz.

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 sınıfı için bir sarmalayıcı sınıfıdır. Uygulamanızın GoogleMap'a eş değer bir API kullanarak haritayla etkileşim kurmasına olanak tanır. Tüketici haritasını kullanmak, uygulamanızın ve araç paylaşımınızın, aynı temel Google Haritası ile sorunsuz bir şekilde etkileşimde bulunmasını sağlar. Örneğin, GoogleMap yalnızca tek bir geri arama kaydına izin verir ancak ConsumerGoogleMap çift kayıtlı geri çağırmayı destekler. Bu geri çağırma işlevleri, uygulamanızın ve araç paylaşımınızın sıralı olarak çağrılan geri çağırmaları kaydetmesine olanak tanır.

ConsumerController

ConsumerController, seyahatleri izleme, gezi durumunu kontrol etme ve konum ayarlama gibi araç paylaşma işlevlerine erişim sağlar.

Yolculuk paylaşımını ayarlayın

Arka uç, tüketiciyi bir araçla eşleştirdikten sonra yolculuk paylaşımı kullanıcı arayüzünü başlatmak için JourneySharingSession öğesini kullanın. Yolculuk paylaşımında, eşleşen araç konumu ve rota gösterilir. SDK'yı uygulamanıza uyguladıktan sonra gezileri izleme, güncellemeleri dinleme ve hataları ele alma işlevlerini ekleyebilirsiniz. Aşağıdaki prosedürlerde arka uç hizmetlerinin yürürlükte olduğu ve tüketicileri araçlarla eşleştirme hizmetlerinizin çalışır durumda olduğu varsayılır.

1. TVS (Tahmini Varış Zamanı) ve aracın varıştan önce kat etmesi gereken mesafe gibi seyahatle ilgili ayrıntıları almak için TripModel nesnesine bir dinleyici kaydedin.

   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 kullanarak gezinizi yapılandırın.

   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)
   

Yolculuk paylaşımını durdur

Artık ihtiyaç duyulmadığında (ör. düzenleyen kullanıcının kaldırılması gibi) yolculuk paylaşımını durdurduğunuzdan emin olun. Yolculuk paylaşımının durdurulması, Fleet Engine'e yapılan ağ isteklerini de durdurur ve bellek sızıntılarını önler.

Aşağıdaki örnek kod, yolculuk paylaşımının nasıl durdurulacağını gösterir.

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

Gezi hatalarını işleme

onTripRefreshError yöntemi, gezi izleme sırasında oluşan hataları gösterir. Tüketici SDK'sı hatalarının eşlemesi Google Cloud Platform için oluşturulan aynı HTTP/RPC yönergelerine uyun. Gezi izleme sırasında sıklıkla karşılaşılan hatalar şunlardır:

Daha fazla bilgi için Tüketici SDK'sı Hatalarını Giderme bölümüne bakın.