Przegląd

Interfejs API Karty w Portfelu Google umożliwia partnerom określenie punktu końcowego, za pomocą którego aktywujesz bilet na przejazd. Jeśli konieczna jest aktywacja, użytkownik zobaczy przycisk „Aktywuj”. Po jego kliknięciu wywołany będzie określony punkt końcowy z parametrami opisanymi poniżej. Przed jego zwróceniem punkt końcowy powinien sprawdzić, czy karta zawiera prawidłowe informacje o wykorzystaniu karty (kod kreskowy lub ogląd). Dopiero wtedy karta w Portfelu użytkownika zostanie zaktualizowana, tak aby zawierała informacje o wykorzystaniu promocji. Pamiętaj, że przed aktywacją nie będą się wyświetlać istniejące informacje o wykorzystaniu promocji.

Interfejs API aktywacji

Punkt końcowy aktywacji jest określony w interfejsie API za pomocą activationOptions w klasie transportu. Partner jest odpowiedzialny za utrzymanie działającego punktu końcowego aktywacji z rozsądnym czasem oczekiwania.

  activationOptions: {
    activationUrl: string
  }
Pole Opis
activationUrl

string

URL punktu końcowego partnera, który byłby wywoływany w przypadku żądań aktywacji. Adres URL powinien być hostowany na HTTPS, a plik robots.txt powinien umożliwiać dostęp do ścieżki adresu URL przez UserAgent:Google-Valuables.

Stan aktywacji jest przechowywany w obiekcie za pomocą pola activationStatus. Prawidłowe stany to NOT_ACTIVATED i ACTIVATED. Punkt końcowy aktywacji powinien zaktualizować obiekt o stan ACTIVATED, a także zapewnić obiektowi prawidłowe informacje o wykorzystaniu promocji, takie jak kod kreskowy lub parametry inspekcji wizualnej. Pole deviceContext może służyć do przypinania urządzenia.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Pole Opis
activationStatus

enum (ActivationStatus)

Stan aktywacji tego obiektu transportu publicznego. Ten stan zmieni reprezentację zgłoszenia i pozwoli użytkownikom na podjęcie działania. Jeśli na przykład w szczegółach zgłoszenia jest renderowany przycisk Aktywuj, jeśli ustawiona jest wartość NOT_ACTIVATED.

Akceptowane wartości:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Kontekst urządzenia, z którym ma być powiązany obiekt. Jeśli zasada jest skonfigurowana, informacje o wykorzystaniu promocji będą zwracane tylko na dane urządzenie.
hasLinkedDevice

boolean

Wskazuje, czy ten obiekt jest obecnie połączony z jednym urządzeniem.
DeviceContext
Pole Opis
deviceToken

string

Jeśli jest ustawiony, informacje o wykorzystaniu promocji będą zwracane do danego urządzenia tylko po aktywacji obiektu. Nie można go używać jako stabilnego identyfikatora do śledzenia urządzenia użytkownika. Może się zmieniać w różnych kartach na tym samym urządzeniu, a nawet w przypadku różnych aktywacji dla tego samego urządzenia. W przypadku ustawienia tej opcji elementy wywołujące muszą też ustawić hasLinkedDevice w aktywowanym obiekcie.

Pamiętaj, że deviceToken pochodzi z pola parametrów aktywacji deviceContext

Przypinanie urządzenia

Przypinanie do urządzenia to funkcja, która umożliwia użytkownikowi aktywowanie biletu na jednym urządzeniu i wyświetlanie informacji o wykorzystaniu biletu tylko na nim. Różni się to od multipleDevicesAndHoldersAllowedStatus właściwości ONE_USER_ONE_DEVICE, które umożliwiają wyświetlanie biletu tylko na 1 urządzeniu. Zalecamy używanie stanu ONE_USER_ALL_DEVICES z przypinaniem urządzenia.

Przed aktywacją użytkownik może zobaczyć bilet i przycisk aktywacji na dowolnym ze swoich urządzeń. Po aktywowaniu i przypięciu na urządzeniu przypięte urządzenie będzie wyświetlać informacje o wykorzystaniu promocji, a na innych urządzeniach pojawi się przycisk aktywacji, który umożliwi użytkownikowi przeniesienie biletu na inne urządzenie. Jeśli przenoszenie zgłoszenia nie jest pożądane, ale aktywacja na dowolnym urządzeniu jest taka sama, można zaktualizować zgłoszenie podczas aktywacji do ONE_USER_ONE_DEVICE, zamiast przypinać urządzenie.

Aby zaimplementować przypinanie urządzeń, należy zaktualizować obiekt za pomocą pola deviceToken, które otrzymuje parametry aktywacji, oraz ustawić hasLinkedDevice na wartość prawda w tym samym wywołaniu interfejsu API. W razie potrzeby można odłączyć zgłoszenie od urządzenia, ustawiając dla atrybutu hasLinkedDevice wartość false (fałsz) w przyszłym wywołaniu interfejsu API.

schemat sekwencji przypinania urządzenia

Parametry aktywacji

Żądanie wysłane do punktu końcowego aktywacji będzie zawierać podane niżej parametry.

Przykład JSON: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

Identyfikator Opis
classId

Pełny i jednoznaczny identyfikator klasy. Używa tego formatu:

<issuer_id.class_id>
objectIds

Pełna i jednoznaczna tablica identyfikatorów obiektów w tym formacie:

<issuer_id.object_id>
expTimeMillis Czas ważności w milisekundach od początku epoki. Po upływie okresu ważności wiadomość musi zostać uznana za nieprawidłową.
eventType Zawsze "activate".
nonce Identyfikator jednorazowy pozwalający śledzić zduplikowane dostawy.
deviceContext

Wygenerowany przez Google unikalny identyfikator urządzenia, na którym użytkownik wykonuje działanie. Tego identyfikatora należy używać podczas aktualizacji, które łączą obiekt z urządzeniem.

Ten identyfikator może nie być stały w przypadku przyszłych żądań z danego urządzenia.