Manda inviti con i Business Generated Link (per gli sviluppatori)

Questa guida è dedicata agli sviluppatori che desiderano creare Business Generated Link. Al suo interno scoprirai come generare collegamenti cifrati usando il tuo linguaggio di programmazione preferito.

IMPORTANTE

Il metodo di invito dei Business Generated Link è disponibile soltanto per i nuovi clienti business di Trustpilot in settori specifici.

NB: per aiutarti a iniziare, Trustpilot ha creato delle risorse sulla Authenticated Encryption su Github. Consultale qui.

Guida per tutti i linguaggi di programmazione

I Business Generated Link usano il tipo di cifratura Authenticated Encryption with Associated Data (AEAD) e un approccio chiamato Encrypt then MAC (EtM). Trustpilot usa una chiave per cifrare il payload (encryptkey) e un'altra chiave per il MAC part (authkey) al fine di garantire l'integrità dei dati.

Dal tuo account business, vai a Raccogli recensioni > Invita i clienti > Business Generated Link per trovare le due chiavi.

Crea Business Generated Link

  1. Le chiavi copiate dal tuo account Trustpilot Business sono mostrate in un formato base64-encoded. Quindi, la prima cosa di cui si deve occupare la tua applicazione è un base64-decode delle chiavi.
  2. Crea l'oggetto payload in formato JSON e inserisci le informazioni del cliente. I seguenti campi sono obbligatori: email, name e ref (= numero di riferimento). Ecco un esempio:
{
  "email":"xyz@dominio.it",
  "name":"Mario Rossi",
  "ref":"1234",
  "skus":["sku1","sku2","sku3"],
  "tags":["tag1","tag2","tag3"]
}
NB: i tag non devono contenere spazi.
  1. Assicurati che il payload non possa essere letto da terze parti cifrando il payload. Cifra con AES-CBC usando una chiave di dimensione 256 bit, un block di dimensione 128 bit e PKCS7 padding mode
  • Genera un Initialization Vector (IV) in funzione della dimensione del block (128 bit)
  • Cifra il JSON con l'encryptkey e con IV
  • Crea una firma per il ciphertext.
  • Per fare questo noi usiamo HMAC-SHA256 e la chiave authkey. Determina il HMAC crittografando (hash) il vettore IV seguito dal ciphertext. Ecco un esempio: HMAC = HMAC-SHA256( IV + ciphertext )
  1. Adesso esegui l'operazione base64-encode sul vettore IV + ciphertext + HMAC. Come questa: base64_payload = base64( IV + ciphertext + HMAC )
  2. Infine, dal momento che base64 include lo slash (/) e il segno più (+), è necessario eseguire un URL-encode del payload descritto qui sopra prima di aggiungerlo al link definitivo.
  3. Il link definitivo dovrebbe avere questo aspetto:
  payload = urlencode( base64_payload )
  https://www.trustpilot.com/evaluate-bgl/<domain>?p=<payload>
  1. Sostituisci il dominio con il nome del tuo dominio e il payload con il payload che hai generato al passaggio 5.

Il diagramma seguente mostra i passaggi necessari per formattare, cifrare e preparare correttamente i dati del payload prima della distribuzione:

Image_1.png

Come verificare un Business Generated Link

Ci sono due modi per verificare che un Business Generated Link sia stato creato correttamente:

Puoi testare il tuo link in un browser

Incolla il tuo link in un browser e avvia la ricerca. Quindi, crea una recensione di prova. Seleziona una valutazione in stelle, aggiungi un titolo e il testo della recensione. Se il pulsante Pubblica la tua recensione adesso è attivo, significa che il tuo processo di cifratura è riuscito. Se ti viene chiesto di accedere tramite Facebook, Google o email, significa che il tuo processo di cifratura non è riuscito. Ricordati di non pubblicare la tua recensione di prova. Ecco un esempio:

Image_2.png

Puoi testare il tuo link con l'interfaccia a riga di comando (CLI)

Puoi installare l'interfaccia a riga di comando (in inglese Command Line Interface o CLI) sul computer che usi per le operazioni di sviluppo. Se riesci a decriptare il tuo payload con l'interfaccia a riga di comando, significa che hai cifrato il payload nel modo corretto.

Codifica Business Generated Link per recensioni dei prodotti

Per raccogliere recensioni dei prodotti con i Business Generated Link, aggiungi gli SKU dei prodotti al tuo payload. Ecco un esempio di un payload che include gli SKU dei prodotti. Si tratta di un semplice array JSON:

{
  "email":"xyz@dominio.it",
  "name":"Mario Rossi",
  "ref":"1234",
  "skus":["sku1","sku2","sku3"]
}

Come faccio a localizzare i Business Generated Link per un paese specifico?

Per localizzare un link, rimuovi il "www." e sostituiscilo con il prefisso internazionale in questione. Per esempio:

https://de.trustpilot.com/evaluate-bgl/?p= oppure https://it.trustpilot.com/evaluate-bgl/?p=

Manda inviti per le Recensioni delle Sedi con i Business Generated Link

Se vuoi usare i Business Generated Link per mandare inviti alla recensione delle tue sedi aziendali, devi aggiungere il campo della posizione quando inserisci le informazioni del cliente all'oggetto del payload. Usa l'ID della sede che hai dato a quella specifica sede.

Ecco un esempio:

{
 "email":"xyz@dominio.it",
 "name":"Mario Rossi",
 "ref":"1234",
 "locationId": "id1",
 "skus":["sku1","sku2","sku3"],
 "tags":["tag1","tag2","tag3"]
}

NB: l'ID della sede fa distinzione tra lettere maiuscole e minuscole.