Android용 소비자 SDK 시작하기

소비자 SDK를 사용하여 주문형 차량 공유 및 배송 솔루션 백엔드 서비스와 통합된 기본 소비자 앱을 빌드하고 실행할 수 있습니다. 활성 경로를 표시하고, 이동 업데이트에 응답하고, 이동 오류를 처리할 수 있는 이동 및 주문 진행 상황 앱을 만들 수 있습니다.

소비자 SDK에는 모듈식 아키텍처가 있으므로 특정 앱에 사용할 API 부분을 사용하고 자체 API, Fleet Engine에서 제공하는 백엔드 서비스, Google Maps Platform의 추가 API와 통합할 수 있습니다.

최소 시스템 요구사항

휴대기기는 Android 5.0 (API 수준 21) 이상을 실행해야 합니다.

기본 요건

운송 및 물류 Android SDK는 Artifact Registry Maven 저장소에 게시됩니다. 저장소에는 SDK의 프로젝트 객체 모델 (.pom) 파일과 오프라인 Javadocs가 포함됩니다.

액세스하기

Google Workspace 고객인 경우 온보딩 중에 google-maps-platform-sdk-users@workspacedomain.com 같은 작업공간 그룹을 만들고 Google에 이름을 제공합니다. 이것이 권장 방법입니다. 그러면 Workspace 그룹이 Maven 저장소 gmp-artifacts/transportation에 대한 액세스 권한을 부여하는 허용 목록에 추가됩니다. 액세스 권한이 필요한 사용자 이메일 및 서비스 계정 이메일이 이 목록에 포함되어 있는지 확인합니다.

조직에서 Workspace 그룹을 만들 수 없는 경우 이러한 아티팩트에 액세스해야 하는 사용자 및 서비스 계정 이메일 목록을 Google에 전송합니다.

로컬 개발

로컬 개발의 경우 Cloud SDK로 로그인해도 됩니다.

gcloud auth login

로그인에 사용되는 이메일은 Workspace 그룹의 구성원이어야 합니다.

자동화 (빌드 시스템 또는 지속적 통합)

권장사항에 따라 자동화 호스트를 설정합니다.

• 프로세스가 Google Cloud 환경 내에서 실행되는 경우 자동 사용자 인증 정보 감지를 사용합니다.

• 그렇지 않으면 서비스 계정 키 파일을 호스트 파일 시스템의 안전한 위치에 저장하고 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 적절하게 설정합니다.

사용자 인증 정보와 관련된 서비스 계정 이메일은 작업공간 그룹의 구성원이어야 합니다.

구성

Maven 또는 Gradle을 구성하여 사용자 또는 서비스 사용자 인증 정보를 자동으로 감지합니다.

plugins {
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.5"
}
repositories {
  maven {
    url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
  }
}

<repositories>
  <repository>
    <id>gmp-artifacts</id>
    <url>artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation</url>
    <releases>
      <enabled>true</enabled>
    </releases>
  </repository>
</repositories>
<build>
  <extensions>
    <extension>
      <groupId>com.google.cloud.artifactregistry</groupId>
      <artifactId>artifactregistry-maven-wagon</artifactId>
      <version>2.1.5</version>
    </extension>
  </extensions>
</build>

액세스 확인에 대한 자세한 내용은 자바 패키지 관리를 참조하세요.

프로젝트 구성

Android용 소비자 SDK를 사용하려면 앱에서 minSdkVersion 19 이상을 타겟팅해야 합니다.

소비자 SDK로 빌드된 앱을 실행하려면 Android 기기에 Google Play 서비스가 설치되어 있어야 합니다.

개발 프로젝트 설정

Google Cloud Console에서 개발 프로젝트를 설정하고 프로젝트의 API 키를 가져오려면 다음 안내를 따르세요.

1. 소비자 SDK와 함께 사용할 새 Google Cloud Console 프로젝트를 만들거나 기존 프로젝트를 선택합니다. 새 프로젝트가 Google Cloud Console에 표시될 때까지 몇 분 정도 기다립니다.

2. 데모 앱을 실행하려면 프로젝트에 Android용 Maps SDK 액세스 권한이 있어야 합니다. Google Cloud Console에서 API 및 서비스 > 라이브러리를 선택한 다음 Android용 Maps SDK를 검색하고 사용 설정합니다.

3. API 및 서비스 > 사용자 인증 정보 > 사용자 인증 정보 만들기 > API 키를 선택하여 프로젝트의 API 키를 가져옵니다. API 키 가져오기에 대한 자세한 내용은 API 키 가져오기를 참조하세요.

앱에 소비자 SDK 추가

소비자 SDK는 비공개 Maven 저장소를 통해 사용할 수 있습니다. 저장소에는 SDK의 프로젝트 객체 모델 (.pom) 파일 및 Javadoc이 포함되어 있습니다. 앱에 소비자 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 자리표시자로 대체합니다.

   Gradle

   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>
   

앱에 API 키 추가

앱에 소비자 SDK를 추가했으면 API 키를 앱에 추가합니다. 개발 프로젝트를 설정할 때 가져온 프로젝트 API 키를 사용해야 합니다.

이 섹션에서는 앱에서 더욱 안전하게 참조할 수 있도록 API 키를 저장하는 방법을 설명합니다. API 키는 버전 제어 시스템에 등록하면 안 됩니다. 이 파일은 프로젝트의 루트 디렉터리에 있는 local.properties 파일에 저장해야 합니다. local.properties 파일에 관한 자세한 내용은 Gradle 속성 파일을 참고하세요.

이 작업을 간단히 진행하고 싶다면 Android용 Secrets Gradle Plugin을 사용하세요.

플러그인을 설치하여 API 키를 저장하는 방법은 다음과 같습니다.

1. 루트 수준 build.gradle 파일을 열고 buildscript 아래의 dependencies 요소에 다음 코드를 추가합니다.

   Groovy

   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 요소에 다음 코드를 추가합니다.

   Groovy

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

   Kotlin

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

3. Android 스튜디오를 사용하는 경우 프로젝트를 Gradle과 동기화합니다.

4. 프로젝트 수준 디렉터리에서 local.properties를 열고 다음 코드를 추가합니다. YOUR_API_KEY를 API 키로 변경합니다.

   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를 사용하는 경우 앱의 법적 고지 섹션의 일부로 저작자 표시 텍스트와 오픈소스 라이선스를 포함해야 합니다. 속성은 독립적인 메뉴 항목 또는 정보 메뉴 항목의 일부로 포함하는 것이 가장 좋습니다.

Ridesharing Consumer SDK ZIP 파일에서 필요한 저작자 표시 텍스트와 오픈소스 라이선스를 찾을 수 있습니다.

• NOTICE.txt
• LICENSES.txt

소비자 SDK 인증

소비자 SDK는 JSON 웹 토큰을 사용하여 인증을 제공합니다. JSON 웹 토큰 (JWT)은 서비스에 대한 하나 이상의 클레임을 제공하는 JSON 기반 액세스 토큰입니다. 예를 들어 서버는 클레임이 '관리자로 로그인됨'인 토큰을 생성하여 클라이언트에 제공할 수 있습니다. 그러면 클라이언트는 이 토큰을 사용하여 관리자로 로그인했음을 증명할 수 있습니다.

소비자 SDK는 Fleet Engine과 통신하기 위해 애플리케이션이 제공하는 JSON 웹 토큰을 사용합니다. 자세한 내용은 Fleet Engine 인증 및 승인을 참고하세요.

승인 토큰은 다음 Fleet Engine 서비스에 대한 액세스를 제공합니다.

• TripService - 차량 위치, 경로, ETA 등 이동 세부정보에 대한 소비자 SDK 액세스 권한을 부여합니다. 왕복 서비스의 승인 토큰에는 tripid:TRIP_ID 클레임이 토큰의 authorization 헤더에 포함되어야 하며, 여기서 TRIP_ID는 경로 ID입니다.
• VehicleService - 차량 밀도 레이어를 표시하고 승차 지점 ETA를 예상하기 위한 퍼징된 차량 위치에 관한 소비자 SDK 정보를 제공합니다. 소비자 SDK는 퍼징된 위치만 사용하므로 차량 서비스의 승인 토큰에는 vehicleid 클레임이 필요하지 않습니다.

JSON 웹 토큰 콜백

소비자 SDK는 초기화 중에 애플리케이션에 승인 토큰 콜백을 등록합니다. SDK는 애플리케이션을 호출하여 승인이 필요한 모든 네트워크 요청의 토큰을 가져옵니다.

콜백 구현 토큰을 승인하고 expiry 시간이 지난 경우에만 갱신하는 것이 좋습니다. 토큰은 1시간 후에 만료됩니다.

승인 토큰 콜백은 TripService 서비스에 필요한 서비스 토큰을 지정합니다. 컨텍스트에 필요한 tripId도 제공합니다.

다음 코드 예는 승인 토큰 콜백을 구현하는 방법을 보여줍니다.

class JsonAuthTokenFactory implements AuthTokenFactory {

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

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

  private CachedToken token;

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

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

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

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

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

    return token;
  }
}

class JsonAuthTokenFactory : AuthTokenFactory() {

  private var token: CachedToken? = null

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

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

    return token.tokenValue
  }

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

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

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

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

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

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

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

      token.tripId = tripId

      return token
    }
  }
}

API 초기화하기

이 절차를 따르기 전에 적절한 서비스와 소비자 SDK를 사용 설정했다고 가정합니다.

ConsumerApi 인스턴스 가져오기

소비자 SDK를 사용하려면 앱에서 ConsumerApi를 비동기식으로 초기화해야 합니다. API는 싱글톤입니다. 초기화 메서드는 AuthTokenFactory를 사용합니다. 팩토리는 필요한 경우 사용자의 새 JWT 토큰을 생성합니다.

providerId는 Google Cloud 프로젝트의 프로젝트 ID입니다. 프로젝트 생성에 관한 자세한 내용은 Fleet Engine 사용자 가이드를 참고하세요.

앱은 소비자 SDK 인증에 설명된 대로 AuthTokenFactory를 구현해야 합니다.

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

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

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

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

사용자 인터페이스 만들기

ConsumerMapFragment 또는 ConsumerMapView를 사용하여 애플리케이션의 사용자 인터페이스를 만들 수 있습니다. ConsumerMapFragment에서는 Fragment를 사용하여 지도를 정의할 수 있으며 ConsumerMapView에서는 View를 사용할 수 있습니다. 차량 공유 기능은 ConsumerMapView 및 ConsumerMapFragment에서 동일하므로 애플리케이션에 View 또는 Fragment 중 어느 것이 더 적합한지에 따라 선택할 수 있습니다.

API 19 (KitKat) 및 벡터 드로어블 지원을 추가합니다.

앱 설계에서 API 19 (KitKat) 기기 및 벡터 드로어블을 지원해야 하는 경우 다음 코드를 활동에 추가하세요. 이 코드는 소비자 SDK에서 벡터 드로어블을 사용하도록 AppCompatActivity를 확장합니다.

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

// ...

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

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

// ...

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

지도 프래그먼트 또는 뷰 추가하기

애플리케이션 프래그먼트 XML 파일 (/res/layout에 있음)에서 정의하는 Android 프래그먼트 또는 뷰에 여정 공유를 표시하는 지도를 만듭니다. 그러면 프래그먼트 (또는 뷰)가 앱에서 공유하고 수정할 수 있는 여정 공유 맵에 대한 액세스를 제공합니다. 또한 지도는 ConsumerController에 핸들을 제공하여 앱에서 여정 공유 환경을 제어하고 맞춤설정할 수 있습니다.

지도 및 컨트롤러 여정 공유

다음 코드 예에서와 같이 여정 공유 지도를 프래그먼트 (ConsumerMapFragment 사용) 또는 뷰 (ConsumerMapView 사용)로 정의합니다. 그러면 onCreate() 메서드는 getConsumerGoogleMapAsync(callback)를 호출하여 콜백에서 ConsumerGoogleMap를 비동기식으로 반환합니다. 그런 다음 ConsumerGoogleMap를 사용하여 탐색 여정 공유를 표시하고 앱에서 필요에 따라 업데이트할 수 있습니다.

소비자 지도 프래그먼트

다음 코드 예에서와 같이 애플리케이션 레이아웃 XML 파일에서 프래그먼트를 정의합니다.

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

getConsumerGoogleMapAsync() 호출은 onCreate() 메서드에서 가져와야 합니다.

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {

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

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

}

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

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

소비자 지도 보기

XML 파일에서 정의된 대로 프래그먼트 또는 활동에서 뷰를 사용할 수 있습니다.

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

getConsumerGoogleMapAsync() 호출은 onCreate()에서 호출되어야 합니다. 콜백 매개변수 외에도, 포함하는 활동 또는 프래그먼트와 MapView의 구성 속성이 포함된 GoogleMapOptions (null일 수 있음)가 필요합니다. 활동 또는 프래그먼트 기본 클래스는 수명 주기에 대한 액세스를 제공하기 때문에 각각 FragmentActivity 또는 지원 Fragment이어야 합니다.

public class SampleAppActivity extends AppCompatActivity {

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

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

}

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

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

프래그먼트의 MapView는 활동의 MapView에 관한 위 예와 동일하지만 프래그먼트가 프래그먼트 onCreateView() 메서드에서 MapView가 포함된 레이아웃을 확장한다는 점을 제외하면 동일합니다.

public class MapViewInFragment extends Fragment {

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

}

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

여정에 집중할 수 있도록 카메라 확대/축소 조정하기

Maps SDK에 기본 제공되는 내 위치 버튼은 카메라를 기기 위치 가운데에 배치합니다.

진행 중인 탐색 여정 공유 세션이 있는 경우 카메라를 기기 위치 대신 여정에 집중시키는 것이 좋습니다.

Android 내장 솔루션용 소비자 SDK: AutoCamera

기기 위치 대신 여정에 집중할 수 있도록 소비자 SDK는 기본적으로 사용 설정된 자동 카메라 기능을 제공합니다. 카메라를 확대하여 여정 공유 경로 및 다음 경로 경유지에 중점을 둡니다.

카메라 동작 맞춤설정

카메라 동작을 더 세밀하게 제어해야 하면 ConsumerController.setAutoCameraEnabled()를 사용하여 자동 카메라를 사용 중지하거나 사용 설정하세요.

ConsumerController.getCameraUpdate()는 그 시점에 권장되는 카메라 경계를 반환합니다. 그런 다음 이 CameraUpdate를 GoogleMap.moveCamera() 또는 GoogleMap.animateCamera()에 대한 인수로 제공할 수 있습니다.

차량 공유 및 지도 액세스

애플리케이션에서 차량 공유 및 지도 상호작용을 지원하려면 ConsumerGoogleMap 및 ConsumerController에 액세스해야 합니다. ConsumerMapFragment 및 ConsumerMapView는 모두 ConsumerMapReadyCallback에서 비동기적으로 ConsumerGoogleMap를 반환합니다. ConsumerGoogleMap는 getConsumerController()에서 ConsumerController를 반환합니다. 다음과 같이 ConsumerGoogleMap 및 ConsumerController에 액세스할 수 있습니다.

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

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

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

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

소비자Google지도

ConsumerGoogleMap는 GoogleMap 클래스의 래퍼 클래스입니다. GoogleMap와 동일한 API를 사용하여 지도와 상호작용할 수 있는 기능을 앱에 제공합니다. 소비자 지도를 사용하면 앱과 차량 공유가 동일한 기본 GoogleMap과 원활하게 상호작용할 수 있습니다. 예를 들어 GoogleMap는 단일 콜백 등록만 허용하지만 ConsumerGoogleMap는 이중 등록 콜백을 지원합니다. 이러한 콜백을 사용하면 앱과 차량 공유에서 순차적으로 호출되는 콜백을 등록할 수 있습니다.

소비자 컨트롤러

ConsumerController를 사용하면 경로 모니터링, 경로 상태 제어, 위치 설정과 같은 차량 공유 기능에 액세스할 수 있습니다.

여정 공유 설정

백엔드가 소비자와 차량을 일치시킨 후 JourneySharingSession를 사용하여 사용자 인터페이스를 공유하는 여정을 시작합니다. 여정 공유는 일치하는 차량 위치와 경로를 보여줍니다. 앱에 SDK를 구현한 후 경로 모니터링, 업데이트 수신 대기, 오류 처리 기능을 추가할 수 있습니다. 다음 절차에서는 백엔드 서비스가 마련되어 있고 차량과 소비자를 연결하는 서비스가 운영된다고 가정합니다.

1. TripModel 객체에 리스너를 등록하여 예상 도착 시간 (ETA) 및 차량이 도착하기 전에 이동해야 하는 거리와 같은 세부 정보를 확인합니다.

   자바

   // Create a TripModel instance for listening to updates to the trip specified by this trip name.
   String tripName = ...;
   TripModelManager tripModelManager = consumerApi.getTripModelManager();
   TripModel tripModel = tripModelManager.getTripModel(tripName);
   
   // Create a JourneySharingSession instance based on the TripModel.
   JourneySharingSession session = JourneySharingSession.createInstance(tripModel);
   
   // Add the JourneySharingSession instance on the map for updating the UI.
   consumerController.showSession(session);
   
   // Register for trip update events.
   tripModel.registerTripCallback(new TripModelCallback() {
     @Override
     public void onTripETAToNextWaypointUpdated(
         TripInfo tripInfo, @Nullable Long timestampMillis) {
       // ...
     }
   
     @Override
     public void onTripActiveRouteRemainingDistanceUpdated(
         TripInfo tripInfo, @Nullable Integer distanceMeters) {
       // ...
     }
   
     // ...
   });
   

   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을 사용하여 경로를 구성합니다.

   자바

   // 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에 대한 네트워크 요청도 중지되고 메모리 누수가 방지됩니다.

다음 샘플 코드는 여정 공유를 중지하는 방법을 보여줍니다.

public class MainActivity extends AppCompatActivity
    implements ConsumerViewModel.JourneySharingListener  {

  // Class implementation

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

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

class SampleAppActivity : AppCompatActivity(), ConsumerViewModel.JourneySharingListener {

  // Class implementation

  override fun onDestroy() {
    super.onDestroy()

    journeySharingSession?.stop()
  }
}

경로 오류 처리

onTripRefreshError 메서드는 이동 모니터링 중에 발생하는 오류를 표시합니다. 소비자 SDK 오류의 매핑은 Google Cloud Platform에 설정된 것과 동일한 HTTP/RPC 가이드라인을 따릅니다. 이동 모니터링 중에 나타나는 일반적인 오류는 다음과 같습니다.

자세한 내용은 소비자 SDK 오류 처리를 참조하세요.