Quando i clienti scelgono un piano tariffario per il tuo software, Google crea un entitlement, che indica che il cliente ha acquistato il tuo prodotto da Google Cloud Marketplace. In questa sezione viene illustrato come creare e gestire i diritti dei tuoi clienti usando l'API Partner Procurement.
Per maggiori dettagli sulla gestione dei diritti, visita la pagina documentazione di riferimento.
Prima di iniziare
- Configura l'accesso all'API Cloud Commerce Partner Procurement, come descritto in Integrare l'app.
Se hai attivato più ordini dello stesso prodotto, l'API Partner Procurement può inviare più eventi con il tipo di eventoENTITLEMENT_ACTIVE per lo stesso valore di ACCOUNT_ID, ciascuno con unENTITLEMENT_ID univoco che rappresenta un'offerta diversa. Ciò significa che devi
Assicurati che la logica di gestione degli eventi dell'app possa rispondere all'ENTITLEMENT_ID
anziché ACCOUNT_ID o PRODUCT_ID.
Devi assicurarti che l'integrazione frontend possa gestire il nuovo oggetto orders
incluso nel payload JWT. Per ulteriori informazioni, consulta
Integrare il frontend dell'app.
Per ulteriori informazioni sull'attivazione di più ordini dello stesso prodotto, vedi Attiva più ordini per lo stesso prodotto.
Approvare un diritto
Quando un cliente sceglie un piano tariffario, Cloud Marketplace crea un e invia il seguente messaggio Pub/Sub alla tua app:
{ "eventId": "...", "eventType": "ENTITLEMENT_CREATION_REQUESTED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "...", "newOfferDuration": "P2Y3M", // Contract duration for offer-based entitlements }, }
dove ENTITLEMENT_ID è un ID creato da Cloud Marketplace. Se l'offerta ha una durata specificata, questa viene fornita in anni e mesi. Se per l'offerta è specificata una data di fine, anziché una durata, il campo che indica che la durata è vuota.
Nel tuo sistema, aggiorna l'account dell'utente in modo che rifletta l'acquisto di un piano. Per approvare il diritto, invia una richiesta HTTP POST all'API Partner Procurement e invia il HTTP POST che stai approvando:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve
Rifiutare un diritto
Per rifiutare un diritto, invia una richiesta HTTP POST all'API Partner Procurement e utilizza il metodo reject nella richiesta:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject
Per fornire un motivo per il rifiuto del diritto nel corpo della richiesta, utilizza il seguente formato:
{ "reason": "..." }
Modificare un piano di diritti
A seconda di come hai configurato i piani tariffari, i tuoi clienti potrebbero essere in grado di e cambiare piano. Se un cliente seleziona un nuovo piano tariffario, ricevi un Messaggio Pub/Sub, nel seguente formato:
{ "eventId": "...", "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "newPlan": "ultimate", // New plan "updateTime": "...", "newOfferDuration": "P2Y3M", // Contract duration for the new offer, for offer-based entitlements }, }
Se l'offerta ha una durata specificata, questa durata viene indicata in anni e mesi. Se per l'offerta è specificata una data di fine, anziché una durata, il campo che indica che la durata è vuota.
Per approvare la modifica del piano, effettua la seguente richiesta HTTP POST al
API Partner Procurement:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange
Il corpo della richiesta deve contenere il piano da approvare:
{
"pendingPlanName": PLAN_NAME
}
Una volta approvata la modifica, ricevi un altro messaggio Pub/Sub quando la modifica diventa effettiva. Nel messaggio, il campo eventType diventa
ENTITLEMENT_PLAN_CHANGED. Per controllare lo stato di un piano:
Richiesta HTTP GET all'API Partner Procurement.
GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID
La risposta è simile alla seguente, con il campo state che indica
se il nuovo piano è attivo o se la modifica del piano è ancora in attesa:
{ "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID", "provider": "YOUR_PARTNER_ID", "account": "USER_ACCOUNT_ID", "product": "example-server", "plan": "pro", "state": "ENTITLEMENT_PENDING_PLAN_CHANGE", "newPendingPlan": "ultimate", ... }
Annullare un diritto
Se un utente decide di annullare il proprio diritto, riceverai un Notifica Pub/Sub. Analogamente alla modifica di un piano, l'annullamento potrebbe essere applicato alla fine del ciclo di fatturazione corrente.
La notifica ha il seguente formato:
{ "eventId": "...", // If the entitlement is canceled at the end of the month, // eventType is ENTITLEMENT_PENDING_CANCELLATION "eventType": "ENTITLEMENT_CANCELLED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "..." }, }
Eliminare un diritto
Se un utente invia una richiesta diretta all'Assistenza Google o se abbandona Google piattaforma, i loro diritti vengono immediatamente annullati e i relativi diritti e vengono eliminati dopo un periodo di tolleranza di 60 giorni. Per proteggere la privacy dell'utente, devi eliminare i suoi dati dai tuoi server quando ricevi una notifica.
Quando i diritti vengono annullati e l'account viene eliminato, ricevi notifiche simili alle seguenti:
{ "eventId": "...", "eventType": "ENTITLEMENT_DELETED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "...", }, }
{ "eventId": "...", "eventType": "ACCOUNT_DELETED", "providerId": "YOUR_PARTNER_ID", "account": { "id": "USER_ACCOUNT_ID", "updateTime": "...", }, }
Elenco dei tipi di eventi per le attività dell'account
Di seguito è riportato un elenco dei eventType che la tua app potrebbe ricevere in
I messaggi Pub/Sub:
| eventType | Descrizione |
|---|---|
| ACCOUNT_CREATION_REQUESTED | Ritirato |
| ACCOUNT_ACTIVE | Indica che l'account del cliente è stato creato. |
| ACCOUNT_DELETED | Indica che l'account del cliente è stato eliminato dai sistemi Google Cloud. |
| ENTITLEMENT_CREATION_REQUESTED | Indica che un cliente ha selezionato uno dei tuoi piani tariffari. |
| ENTITLEMENT_OFFER_ACCEPTED | Indica che un'offerta è stata accettata da un cliente. Include l'ora di inizio pianificata dell'offerta, se esistente. Questo evento viene inviato sia per le offerte private sia per quelle standard (acquisti pubblici). |
| ENTITLEMENT_ACTIVE | Indica che il piano scelto da un cliente è ora attivo. |
| ENTITLEMENT_PLAN_CHANGE_REQUESTED | Indica che un cliente ha scelto un nuovo piano. |
| ENTITLEMENT_PLAN_CHANGED | Indica che la modifica del piano di un cliente è stata approvata e che le modifiche sono state applicate. |
| ENTITLEMENT_PLAN_CHANGE_CANCELLED | Indica che la modifica del piano di un cliente è stata annullata perché non è stata approvata o perché è tornato al piano precedente. |
| ENTITLEMENT_PENDING_CANCELLATION | Indica che un cliente ha annullato il proprio piano e che l'annullamento è in attesa fino al termine del ciclo di fatturazione. |
| ENTITLEMENT_CANCELLATION_REVERTED | Indica che l'annullamento in attesa di un cliente è stato annullato. Tieni presente che le cancellazioni non possono essere annullate una volta finalizzate. |
| ENTITLEMENT_CANCELLED | Indica che il piano di un cliente è stato annullato. |
| ENTITLEMENT_CANCELLING | Indica che il piano di un cliente è in fase di annullamento. |
| ENTITLEMENT_RENEWED | Indica che il diritto di un cliente è stato rinnovato per un altro periodo. Non è richiesta alcuna azione da parte tua per completare il rinnovo. |
| ENTITLEMENT_OFFER_ENDED | Indica che l'offerta privata di un cliente è terminata. Se il diritto del cliente è stato annullato, viene attivato un evento ENTITLEMENT_CANCELLED separato. Se il diritto del cliente è ancora attivo, il piano tornerà al prezzo non scontato. |
| ENTITLEMENT_DELETED | Indica che le informazioni sul piano di un cliente sono state eliminate da Cloud Marketplace. |