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. |