Przeznaczenie

Klasa kart definiuje zestaw właściwości, które są wspólne dla wielu kart, podobnie jak szablon. Jeśli na przykład wydajesz bilety na wydarzenie, klasa kart zdefiniuje takie same pola we wszystkich biletach, takie jak nazwa, data i godzina wydarzenia.

Każdy wydany dokument musi odwoływać się do klasy kart. Do każdej utworzonej klasy karty musisz przypisać unikalny identyfikator, który będzie używany podczas tworzenia kart.

Jak to się robi

Klasa kart jest zdefiniowana w formacie JSON i można ją utworzyć za pomocą interfejsu API Portfela Google typu REST, pakietu SDK na Androida lub w konsoli biznesowej Portfela Google.

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "logo": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "LOGO_IMAGE_DESCRIPTION"
      }
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW",
  "hexBackgroundColor": "#264750",
  "heroImage": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "HERO_IMAGE_DESCRIPTION"
      }
    }
  }
}
    

Przeznaczenie

Obiekt kart definiuje właściwości unikalnej karty, która zostanie wydana konkretnemu użytkownikowi. Na przykład obiekt karty biletu na wydarzenie będzie definiować pola unikalne dla konkretnego biletu, takie jak numer miejsca lub kod QR tego biletu.

Po utworzeniu obiektu karty interfejs Google Wallet API przechowuje nową kartę i wiąże ją z Twoim kontem wydawcy. Ta karta zapisana jest kombinacją unikalnych właściwości obiektu z kartami i właściwości szablonu powiązanej klasy kart.

Każdemu obiektowi karty musisz też przypisać unikalny identyfikator, który posłuży do odwoływania się do niego podczas wystawiania karty.

Jak to się robi

Obiekt karty jest zdefiniowanym w formacie JSON i można go utworzyć za pomocą interfejsu API Portfela Google typu REST lub pakietu SDK na Androida.

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "5"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "G"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "40"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "3A"
      }
    }
  },
  "barcode": {
    "type": "QR_CODE",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}
    

Przeznaczenie

Aby wydać kartę użytkownikowi, obiekt klasy i kart musi być zakodowany w tokenie sieciowym JSON (JWT). Format JWT jest wspólnym i otwartym standardem do przedstawiania roszczeń między 2 stronami. W przypadku wystawiania kart za pomocą interfejsu Google Wallet API, tokeny JWT są używane do wysłania deklaracji, że użytkownik ma prawo dostępu do określonej karty powiązanej z Twoim kontem wydawcy.

Gdy token JWT jest wysyłany do interfejsu Google Wallet API, zakodowane dane służą do identyfikowania konkretnej karty i wydania jej użytkownikowi. Jeśli karta została już wystawiona, dane te pozwalają interfejsowi Google Wallet API na zidentyfikowanie, że karta jest duplikatem, dzięki czemu nie zostanie ona dodana do Portfela Google użytkownika więcej niż raz.

Jak to się robi

Tokeny JWT są zdefiniowane w formacie JSON na podstawie specyfikacji JWT. Aby zdefiniować token JWT na potrzeby wydania karty przy użyciu interfejsu Google Wallet API, podaj we właściwości payload tego tokena informacje o karcie.

{
  "iss": "issuer@example.com",
  "aud": "google",
  "typ": "savetowallet",
  "iat": 1696877738,
  "origins": [
    "www.example.com"
  ],
  "payload": {
    "eventTicketObjects": [
      {
        "id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX"
      }
    ]
  }
}
    

Przeznaczenie

Wszystkie tokeny JWT wysyłane do interfejsu API Portfela Google w celu wystawienia karty muszą być podpisane za pomocą danych logowania podanych wcześniej w konsoli biznesowej Portfela Google. Podpisywanie używa Twoich danych logowania do szyfrowania tokena JWT, dzięki czemu karty pozostają bezpieczne, a interfejs API Portfela Google może uwierzytelniać, czy zakodowane w niej dane karty są prawidłowe i powiązane z Twoim kontem wydawcy.

Jak to się robi

Biblioteki klienta Portfela Google i pakiet SDK Androida zapewniają wygodne metody podpisywania tokenów JWT. Istnieją również liczne biblioteki open source, które obsługują złożoność podpisywania kodu.

Osoby używające interfejsu API typu REST Portfela Google do wystawiania kart token JWT jest podpisany kluczem konta usługi Google Cloud. W przypadku pakietu SDK Portfela Google na Androida pakiet SDK automatycznie obsługuje podpisywanie JWT za pomocą odcisku cyfrowego SHA-1 certyfikatu podpisywania aplikacji.

Aby chronić swoje dane logowania, tokeny JWT powinny być podpisane tylko na serwerze lub za pomocą pakietu SDK Portfela Google na Androida w aplikacji.

  // Create the JWT as a HashMap object
  HashMap claims = new HashMap();
  claims.put("iss", ((ServiceAccountCredentials) credentials).getClientEmail());
  claims.put("aud", "google");
  claims.put("origins", Arrays.asList("www.example.com"));
  claims.put("typ", "savetowallet");

  // Create the Google Wallet payload and add to the JWT
  HashMap payload = new HashMap();
  payload.put("eventTicketObjects", Arrays.asList(newObject));
  claims.put("payload", payload);

  // Google Cloud service account credentials are used to sign the JWT
  Algorithm algorithm =
      Algorithm.RSA256(
          null, (RSAPrivateKey) ((ServiceAccountCredentials) credentials).getPrivateKey());
  String token = JWT.create().withPayload(claims).sign(algorithm);
        

  // Create the JWT claims
  let claims = {
    iss: this.credentials.client_email,
    aud: 'google',
    origins: ['www.example.com'],
    typ: 'savetowallet',
    payload: {
      eventTicketObjects: [newObject]
    },
  };

  // The service account credentials are used to sign the JWT
  let token = jwt.sign(claims, this.credentials.private_key, { algorithm: 'RS256' });
        

  # Create the JWT claims
  claims = {
      'iss': self.credentials.service_account_email,
      'aud': 'google',
      'origins': ['www.example.com'],
      'typ': 'savetowallet',
      'payload': {
          # The listed classes and objects will be created
          'eventTicketObjects': [new_object]
      }
  }

  # The service account credentials are used to sign the JWT
  signer = crypt.RSASigner.from_service_account_file(self.key_file_path)
  token = jwt.encode(signer, claims).decode('utf-8')
        

Przeznaczenie

Gdy utworzysz podpisany token JWT, możesz wydać kartę użytkownikowi Portfela Google. Użytkownik ma do dyspozycji przycisk lub link „Dodaj do Portfela Google”. Gdy użytkownik kliknie przycisk lub hiperlink, podpisany token JWT jest wysyłany do interfejsu Google Wallet API, który odszyfrowuje go przy użyciu zapisanych danych logowania. Po uwierzytelnieniu podpisu JWT użytkownik otrzymuje kartę, którą może zapisać w Portfelu Google.

Jak to się robi

Aby utworzyć przycisk „Dodaj do Portfela Google” dla aplikacji na Androida, skorzystaj z pakietu SDK Portfela Google na Androida, który udostępnia metody jego generowania. Na wszystkich innych platformach, w tym w internecie, e-mailach i SMS-ach, utwórz hiperlink w formacie https://pay.google.com/gp/v/save/<signed_jwt>. Jeśli jest to możliwe, najlepiej dostarczyć użytkownikowi ten link jako przycisk „Dodaj do Portfela Google”.

Więcej informacji o korzystaniu z przycisku „Dodaj do Portfela Google” znajdziesz we wskazówkach dotyczących marki interfejsu API Portfela Google

  https://pay.google.com/gp/v/save/<signed_jwt>
        

  private lateinit var walletClient: PayClient
  private val addToGoogleWalletRequestCode = 1000
  private lateinit var addToGoogleWalletButton: View

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    walletClient = Pay.getClient(this)
    addToGoogleWalletButton.setOnClickListener {
      walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
    }
  }
        

Gdy użytkownik zapisze wydaną kartę, pojawi się ona w aplikacji Portfel Google wraz ze wszystkimi innymi zapisanymi przez niego kartami.