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

İsteğe Bağlı Yolculuk ve Teslimat Çözümleri 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örüntüleyebilen, gezi güncellemelerine yanıt verebilen ve gezi hatalarını işleyebilen bir Gezi ve Sipariş İlerleme Durumu uygulaması oluşturabilirsiniz.

Tüketici SDK'sı modüler bir mimariye sahip olduğundan uygulamanız için kullanmak istediğiniz API'nin parçalarını kullanıp kendi API'leriniz, Fleet Engine'in sağladığı arka uç hizmetleri ve Google Haritalar Platformu'ndaki ek API'lerle entegre edebilirsiniz.

Minimum sistem gereksinimleri

Mobil cihazın Android 6.0 (API düzeyi 23) veya sonraki bir sürümü çalıştırıyor olması gerekir.

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

Tüketici SDK'sının 1.99.0 ve üzeri sürümleri, Google Maven deposu kullanılarak kullanılabilir. Daha önce kullanılan özel kod deposu 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 ayarlamak ve Google Cloud Console'da proje için bir API anahtarı almak için:

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

2. Demo uygulamayı çalıştırmak için 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, ardından Android için Haritalar SDK'sını bulup etkinleştirin.

3. API'ler ve Hizmetler > Kimlik Bilgileri > Kimlik bilgileri 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ına özel bir Maven deposu üzerinden erişebilirsiniz. Bu depo, SDK'nın Proje Nesne Modeli (.pom) dosyalarını ve Java belgelerini içerir. Tüketici SDK'sını uygulamanıza eklemek için:

1. Bir önceki bölümde açıklandığı gibi, ana makine Maven deposuna erişmek için ortamınızı ayarlayın.

   settings.gradle ürününde tanımlanmış merkezi bir bağımlılık yönetimi yapılandırması varsa bunu aşağıdaki şekilde devre dışı bırakın.

   • settings.gradle içindeki şu 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. VERSION_NUMBER yer tutucusunu Tüketici SDK'sının istenen sürümü ile değiştirerek aşağıdaki bağımlılığı Gradle veya Maven yapılandırmanıza ekleyin.

   Gradle

   build.gradle cihazınıza aşağıdakileri ekleyin:

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

   Maven

   pom.xml cihazınıza aşağıdakileri 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ının sürümü derleme yapılandırma dosyasında aşağıdaki gibi açıkça tanımlanmamışsa, yeni bir Haritalar SDK'sı sürümü yayınlandığında Tüketici SDK'sı, kendisi için gereken desteklenen minimum Haritalar SDK'sı sürümünü kullanmaya devam edecektir.

   Gradle

   build.gradle cihazınıza aşağıdakileri ekleyin:

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

   Maven

   pom.xml cihazınıza aşağıdakileri 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 ekleme

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ın daha güvenli bir şekilde referans gösterebilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize girmemelisiniz. Bu dosya, projenizin kök dizininde bulunan local.properties dosyasında depolanmalıdır. local.properties dosyası hakkında daha fazla bilgi için Gradle özelliği dosyaları bölümüne bakın.

Bu görevi kolaylaştırmak için Android için Secrets Gradle Plugin'i 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 aşağıdaki kodu plugins öğesine 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üzeyi dizininizde local.properties dosyasını açın ve aşağıdaki kodu ekleyin. YOUR_API_KEY öğesini 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 gidip android:value özelliğini aşağıdaki gibi 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 manifestin tamamı 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>

Gerekli ilişkilendirmeleri uygulamanıza dahil edin

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

Lisans bilgileri, arşivlenmemiş 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 sayfasına bakın.

Tüketici SDK Kimlik Doğrulaması

Tüketici SDK'sı, JSON Web Jetonlarını 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ına sahip bir jeton oluşturabilir ve bunu istemciye sağlayabilir. Ardından istemci, yönetici olarak giriş yaptığını kanıtlamak için bu jetonu kullanabilir.

Tüketici SDK'sı, Fleet Engine ile iletişim kurmak için uygulama tarafından sağlanan JSON Web Jetonu'nu kullanır. Daha fazla bilgi için Filo Motoru Kimlik Doğrulaması ve Yetkilendirme sayfasına göz atın.

Yetkilendirme jetonunun, jetonun authorization başlığında bir tripid:TRIP_ID talebi içermesi gerekir. Burada TRIP_ID, gezi kimliğidir. Bu, Tüketici SDK'sının araç konumu, rota ve TVS dahil seyahat ayrıntılarına erişmesini sağlar.

JSON Web Token geri çağırma işlemleri

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 alması için uygulamaya çağrıda bulunur.

Geri çağırma uygulamanız için ö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 sağlar.

Aşağıdaki kod örneği, bir 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 alma

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

providerId, Google Cloud Projenizin Proje Kimliğidir. Projenin oluşturulması hakkında daha fazla bilgi için Fleet Engine Kullanıcı Kılavuzu'na göz atın.

Uygulamanız, AuthTokenFactory özelliğini Tüketici SDK'sı Kimlik Doğrulaması bölümünde açıklandığı gibi 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
}

Tercih edilen oluşturucuyu istemek için Google Haritalar SDK'sını başlatın

Tüketici SDK'sı 2.0.0 sürümü, Android 18.1.0 ve üzeri için Haritalar SDK'sını destekler. Tercih edilen Google Haritalar oluşturucusunu belirten istekleri destekler. Ayrıntılar için Yeni Harita Oluşturucu(etkinleştirme) bölümüne bakın.

Haritalar SDK'sını bağımlılık olarak ekleme

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

 <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ı ilk kullanıma hazırlayın

Application veya başlangıç Activity sınıfınızda MapsInitializer.initialize() yöntemini çağırın ve Tüketici SDK'sını başlatmadan önce oluşturucu isteği 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ızı, ConsumerMapView ise View kullanmanızı sağlar. Araç paylaşma işlevi hem ConsumerMapView hem de ConsumerMapFragment'da aynıdır. Bu nedenle View veya Fragment'in uygulamanız için daha uygun olup olmadığına bağlı olarak birini seçebilirsiniz.

API 19 (KitKat) ve Vektör çekilebilir öğeleri için destek eklendi

Uygulama tasarımınız API 19 (KitKat) cihazları ve vektör çekilebilir öğelerini gerektiriyorsa aşağıdaki kodu Etkinliğinize ekleyin. Bu kodlar, Tüketici SDK'sındaki Vektör çekilebilirlerini kullanmak için AppCompatActivity kodunu 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ünü ekleme

Yolculuk paylaşımını, uygulama düzeni XML dosyanızda (/res/layout konumunda) tanımladığınız bir Android parçası veya görünümde görüntülemek üzere haritayı oluşturursunuz. Parça (veya görünüm) daha sonra 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 edip özelleştirmesini sağlayan bir tutma yeri de sağlar. ConsumerController

Yolculuk paylaşımı haritası ve kumandası

Yolculuk paylaşım haritasını, aşağıdaki kod örneğinde gösterildiği gibi parça (ConsumerMapFragment kullanılarak) veya görünüm (ConsumerMapView kullanılarak) olarak tanımlarsınız. Daha sonra onCreate() yönteminiz, geri çağırmada ConsumerGoogleMap eşzamansız olarak döndüren getConsumerGoogleMapAsync(callback) yöntemini çağırır. Daha sonra, yolculuk paylaşımını görüntülemek için ConsumerGoogleMap öğesini kullanırsınız ve bu değer, uygulamanızın gerektirdiği şekilde güncellenebilir.

ConsumerMapFragment

Parçayı, aşağıdaki kod örneğinde gösterildiği gibi uygulama düzeni XML dosyanızda 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 etkinlik içinde 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 çağrı, onCreate() konumundan gelmelidir. Geri çağırma parametresine ek olarak, kapsayıcı etkinliği veya parçasını ve MapView için yapılandırma özelliklerini içeren GoogleMapOptions öğesini (boş olabilir) gerektirir. Etkinlik veya parça temel sınıfı, yaşam döngüsüne erişim sağladığı için sırasıyla FragmentActivity veya destek Fragment 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 etkinlikte yukarıdaki MapView örneğiyle aynıdır. Tek fark, parçanın onCreateView() parçası yöntemindeki MapView öğesini içeren düzeni şişirmesidir.

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

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

Etkin bir Yolculuk Paylaşımı oturumu varsa cihazın konumu yerine yolculuğa odaklanmak için kamerayı ortalamak isteyebilirsiniz.

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

Tüketici SDK'sı, cihazın konumu yerine yolculuğa odaklanmanızı sağlamak için varsayılan olarak etkin olan bir AutoKamera özelliği sağlar. Kamera, yolculuğun paylaşıldığı rotaya ve bir sonraki gezi ara noktasına odaklanmak için görüntüyü yakınlaştırı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(), o andaki önerilen kamera sınırlarını döndürür. Daha sonra bu CameraUpdate öğesini, GoogleMap.moveCamera() veya GoogleMap.animateCamera() işlevine bir bağımsız değişken olarak sağlayabilirsiniz.

Araç paylaşma ve haritalara erişim

Uygulamanızda araç paylaşımı ve harita etkileşimini desteklemek için ConsumerGoogleMap ve ConsumerController erişimine sahip olmanız gerekir. Hem ConsumerMapFragment hem de ConsumerMapView, ConsumerMapReadyCallback içinde eşzamansız olarak ConsumerGoogleMap değerini döndürür. ConsumerGoogleMap, getConsumerController() adlı satıcıdan ConsumerController iade ediyor. ConsumerGoogleMap ve ConsumerController özelliklerine 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 ile eş değer bir API kullanarak haritayla etkileşim kurmasına olanak tanır. Tüketici haritasını kullanmak, uygulama ve araç paylaşımınızın temel Google Haritası ile sorunsuz bir şekilde etkileşime geçmesini sağlar. Örneğin, GoogleMap yalnızca tek bir geri çağırma kaydına izin verirken ConsumerGoogleMap, çift kayıtlı geri çağırmaları destekler. Bu geri çağırma işlevleri, uygulama ve araç paylaşımınızın sıralı olarak çağrılan geri çağırmaları kaydetmesine olanak tanır.

ConsumerController

ConsumerController; seyahat izleme, gezi durumunu kontrol etme ve konum belirleme gibi yolculuk paylaşma işlevlerine erişim sağlar.

Yolculuk paylaşımını ayarlama

Arka uç, bir tüketiciyi araçla eşleştirdikten sonra kullanıcı arayüzünü paylaşma yolculuğuna başlamak için JourneySharingSession öğesini kullanın. Yolculuk paylaşımı, eşleşen araç konumunu ve rotasını gösterir. 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 kullanımda olduğu ve tüketicileri araçlarla eşleştirme hizmetlerinizin çalışır durumda olduğu varsayılır.

1. Seyahatle ilgili TVS (Tahmini Varış Zamanı) ve aracın varıştan önce kat etmesi gereken mesafe gibi ayrıntıları almak için bir TripModel nesnesine 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 gerekli olmadığı durumlarda (ör. düzenleyen etkinliği silindiğinde) 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ı nasıl durduracağınızı 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ı eşleme, Google Cloud Platform için belirlenen HTTP/RPC yönergelerini izler. Gezi izleme sırasında karşılaşılan yaygın hatalar şunlardır:

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