Karty połączone automatycznie

Tło

Funkcja automatycznego łączenia kart umożliwia wysyłanie dodatkowych kart do użytkownika, który ma już Twoją kartę w Portfelu Google. Możesz też wstępnie połączyć karty z kartą podstawową, gdy użytkownik zapisze podstawową (główną) kartę. Automatycznie połączona karta jest zgrupowana z kartą główną. Nad kartą główną znajduje się wywołanie informujące użytkownika o tym, że połączono nową kartę. Jako karty podstawowe lub połączone obsługiwane są te typy kart:

• Bilet na wydarzenie
• Karta pokładowa
• Bilet
• Oferta
• Karta podarunkowa
• Karta lojalnościowa
• Standardowa karta

Karta podstawowa z informacją o dodaniu nowej karty	Nowa karta połączona z kartą podstawową

Przypadki użycia

Możesz mieć różne przypadki użycia linkowania kart do istniejącej karty. Przykłady:

• Połącz ofertę specjalną z istniejącą kartą lojalnościową.
• Połącz kupon na posiłek z kartą pokładową lub biletem na wydarzenie.
• Połącz kartę parkingową z biletem na wydarzenie.

Uwagi dotyczące korzystania z automatycznie połączonych kart

• Obiekt podstawowy i połączony muszą używać tego samego identyfikatora wydawcy.
• Na każdy obiekt główny może przypadać maksymalnie 50 obiektów połączonych.
• Automatyczne przesyłanie połączonych kart nie jest gwarantowane i jest traktowane jako działanie podejmowane w miarę możliwości. Użytkownicy mogą zrezygnować z otrzymywania automatycznie połączonych dokumentów. Jeśli przypadek użycia jest krytyczny i użytkownik musi otrzymać połączoną kartę, zalecamy komunikację za pomocą innego kanału, aby mieć pewność, że użytkownik doda kartę.
• Aktualizacje zasad dopuszczalnego użytkowania Portfela Google zawierają wytyczne dotyczące korzystania z automatycznie połączonych kart, których należy przestrzegać.

Kroki integracji

Jeśli masz już utworzony obiekt podstawowy, możesz pominąć krok 1.

1. Utwórz obiekt dowolnego typu karty z wymaganymi parametrami. Jest to główny obiekt.
2. Utwórz kolejny obiekt dowolnego wymienionego typu karty. Będzie to połączony obiekt.
3. Przed zapisaniem podstawowego obiektu lub po jego zapisaniu zaktualizuj podstawowy obiekt, podając identyfikator połączonego obiektu w parametrze linkedObjectIds.

Aby ustawić identyfikatory linkedObjectIds w podstawowej karcie, wymagany jest minimalny rozmiar ładunku. 3 wymagane parametry to:

1. ISSUERID.PRIMARY_OBJECT_ID
2. ISSUERID.PRIMARY_CLASS_ID
3. ISSUERID.LINKED_OBJECT_ID

Przykładowe żądanie JSON dodania połączonego obiektu do obiektu karty

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": ["ISSUERID.LINKED_PASS_OBJECTID"]
  }
  …

Przykładowa odpowiedź JSON po połączeniu obiektu z obiektem karty

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

oczekiwane zachowanie;

Po otrzymaniu odpowiedzi z informacją o sukcesie urządzenia z zaktualizowaną kartą powinny otrzymać powiązaną kartę. Połączony dokument zostanie zgrupowany z dokumentem podstawowym. Użytkownicy mogą zobaczyć połączony dokument, przesuwając palcem w prawo.

Obsługa wyjątków

W przypadku nieprawidłowego użycia interfejsu API mogą wystąpić błędy, w tym: