Wprowadzenie
Funkcja automatycznie połączonych kart umożliwia wysyłanie dodatkowych kart do użytkownika, który ma już Twoją kartę w swoim Portfelu Google. Możesz też utworzyć połączenie wstępne do karty podstawowej, gdy użytkownik zapisze kartę główną. Karnet połączony automatycznie jest zgrupowany z kartą podstawową. Nad kartą podstawową pojawia się komunikat informujący użytkownika o połączeniu nowej karty. Poniższe typy kart są obsługiwane jako karty podstawowe lub połączone:
- Bilet na wydarzenie
- Karta pokładowa
- Bilet na przejazd
- Oferta
- Karta podarunkowa
- Karta lojalnościowa
- Bilet standardowy
Główna karta z objaśnieniem informującym o dodaniu nowej karty | Nowa karta połączona z kartą podstawową |
Przykłady zastosowania
Przypadki użycia łączenia kart z dotychczasową kartą mogą być różne. 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łączyć bilet parkingowy z biletem na wydarzenie,
Kilka uwag na temat korzystania z automatycznie połączonych kart
- Obiekt główny i połączony obiekt muszą używać tego samego identyfikatora wydawcy.
- Obowiązuje limit 50 połączonych obiektów na obiekt główny.
- Automatyczne przekazywanie połączonych kart nie jest gwarantowane i traktowane jest to w ramach najlepszych starań. Użytkownicy mogą zrezygnować z otrzymywania automatycznie połączonych kart. Jeśli przypadek użycia jest krytyczny i użytkownik musi otrzymać powiązaną kartę, zalecamy nawiązanie kontaktu za pomocą innego kanału, aby mieć pewność, że użytkownik doda kartę.
- Aktualizacje Zasad dopuszczalnego użytkowania Portfela Google obejmują wskazówki na temat korzystania z kart połączonych automatycznie, których należy przestrzegać.
Etapy integracji
Jeśli masz już utworzony obiekt primary, możesz pominąć krok 1.
- Utwórz obiekt dowolnego typu karty wymienionego z wymaganymi parametrami. Jest to obiekt podstawowy.
- Utwórz kolejny obiekt dowolnego z wymienionych typów karty. Będzie to obiekt linked.
- Przed zapisaniem obiektu głównego lub po nim zaktualizuj obiekt główny o identyfikator połączonego obiektu w parametrzelinkedObjectIds.
Do ustawienia powiązanych obiektów w głównej karcie wymagany jest minimalny ładunek. Wymagane są te 3 parametry:
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- ISSUERID.LINKED_OBJECT_ID
Przykładowe żądanie JSON dotyczące 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;
Gdy otrzymasz odpowiedź, powiązaną kartę otrzymają urządzenia ze zaktualizowaną kartą. Ta połączona karta zostanie zgrupowana razem z kartą podstawową. Użytkownicy mogą wyświetlić powiązany bilet, przesuwając palcem w prawo.
Obsługa wyjątków
W przypadku nieprawidłowego korzystania z interfejsu API mogą wystąpić potencjalne błędy, takie jak:
Wiadomość | Uzasadnienie |
---|---|
Obiekt główny i połączony obiekt nie mają tego samego identyfikatora wydawcy. | Nie możesz dołączyć połączonego obiektu do obiektu innego wydawcy. |
Obiekt główny i połączony obiekt odwołują się do tego samego obiektu. | Nie możesz dołączyć tego samego obiektu co połączonyObject. |
Połączony obiekt nie istnieje. | Połączony obiekt powinien być już wstawiony do interfejsu Wallet API. |
Połączony obiekt ma już inny połączony obiekt. Nie można dodać połączonych obiektów. | Połączone obiekty nie mogą mieć innego połączonego obiektu. |
Obiekt jest już połączony z innym obiektem. Nie można dodać zagnieżdżonych połączonych obiektów. | Obiekt główny nie może być obiektem połączonym samodzielnie. |
Nie można dodać więcej połączonych obiektów. Przekroczono limit. | Osiągnięto limit 50 połączonych kart dla głównej karty. |