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ż połączyć karty wstępnie z kartą główną, gdy użytkownik zapisze kartę główną. Karta połączona automatycznie jest pogrupowana z główną kartą, a nad nią znajduje się objaśnienie informujące użytkownika o połączeniu nowej karty. Jako karty główne lub powiązane karty obsługiwane są te typy kart:

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

Podstawowa karta z objaśnieniem, że dodano nową kartę	nowa karta połączona z kartą główną.

Przykłady zastosowania

Możesz mieć różne przypadki użycia łączenia kart z dotychczasowymi kartami. Oto kilka przykładów:

• Połącz ofertę 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.

Wskazówki dotyczące korzystania z automatycznie połączonych kart

• Obiekt główny i połączony obiekt muszą mieć ten sam identyfikator wystawcy.
• Obowiązuje limit 50 połączonych obiektów na obiekt główny.
• Przesyłanie połączonych kart automatycznie nie jest gwarantowane i jest uznawane za najlepsze rozwiązanie. Użytkownicy mogą zrezygnować z otrzymywania automatycznie połączonych kart. Jeśli jest to kluczowe, aby użytkownik otrzymał powiązany bilet, zalecamy komunikację za pomocą innego kanału, aby mieć pewność, że użytkownik doda bilet.
• Aktualizacje Warunków korzystania z Portfela Google zawierają wskazówki dotyczące korzystania z automatycznie połączonych kart, których należy przestrzegać.

Etapy integracji

Jeśli masz już utworzony obiekt główny, możesz pominąć krok 1.

1. Utwórz obiekt dowolnego z wymienionych typów z wymaganymi parametrami. Jest to główny obiekt.
2. Utwórz kolejny obiekt dowolnego z wymienionych typów. To będzie połączony obiekt.
3. Przed zapisaniem głównego obiektu lub po jego zapisaniu zaktualizuj ten obiekt za pomocą identyfikatora połączonego obiektu w parametrze linkedObjectIds.

Aby ustawić identyfikatory obiektów powiązanych na poziomie głównego tokena dostępu, wymagana jest minimalna ilość danych. 3 wymagane parametry:

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

Przykład żądania JSON służącego do dodawania połączonego obiektu do obiektu dokumentu

  …
  {
    "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 urządzenia z zaktualizowanymi kartami powinny otrzymać połączone karty. Połączony bilet będzie grupowany z biletem głównym. Użytkownicy mogą zobaczyć powiązany dokument, przesuwając palcem w prawo.

Obsługa wyjątków

Potencjalne błędy mogą wystąpić w przypadku nieprawidłowego użycia interfejsu API. Oto niektóre z nich:

Wiadomość	Uzasadnienie
Obiekt główny i połączony obiekt nie mają tego samego identyfikatora wydawcy.	Nie można dołączyć połączonego obiektu do obiektu innego wydawcy.
Obiekt główny i połączony odwołują się do tego samego obiektu.	Nie możesz dołączyć tego samego obiektu co połączonyObject.
Powiązany obiekt nie istnieje.	Połączony obiekt powinien już zostać wstawiony do interfejsu Wallet API.
Połączony obiekt ma już inny połączony obiekt. Nie można dodawać zagnieżdżonych obiektów połączonych.	Połączone obiekty nie mogą mieć innego połączonego obiektu.
Obiekt jest już połączony z innym obiektem. Nie można dodawać zagnieżdżonych obiektów połączonych.	Obiekt główny nie może być sam w sobie połączonym obiektem.
Nie można dodać więcej połączonych obiektów. Przekroczono limit.	Osiągnięto limit 50 połączonych kart dla karty głównej.