Documentazione Guida per gli sviluppatori di Target

Identificazione utente e bucket

Ultimo aggiornamento: 20 luglio 2024

Argomenti:

Creato per:

Sviluppatore

Identificazione utente

Un utente può essere identificato in più modi in Adobe Target. Target utilizza i seguenti identificatori:

Nome campo	Descrizione
`tntID`	`tntId` è l'identificatore primario in Target per un utente. È possibile specificare questo ID oppure Target lo genererà automaticamente se la richiesta non ne contiene uno.
`thirdPartyId`	`thirdPartyId` è l'identificatore dell'utente della tua società, che puoi inviare con ogni chiamata. Quando un utente accede al sito di un’azienda, l’azienda in genere crea un ID associato all’account del visitatore, alla carta fedeltà, al numero di iscrizione o ad altri identificatori applicabili per l’azienda.
`marketingCloudVisitorId`	`marketingCloudVisitorId` viene utilizzato per unire e condividere dati tra diverse soluzioni Adobe. MarketingCloudVisitorId è richiesto per le integrazioni con Adobe Analytics e Adobe Audience Manager.
`customerIds`	Oltre all'ID visitatore Experience Cloud, è possibile utilizzare ID cliente aggiuntivi e uno stato autenticato per ogni visitatore.

ID Target (tntID)

L'ID Target, o tntId, può essere considerato un ID dispositivo. tntId viene generato automaticamente da Adobe Target se non viene fornito nella richiesta. Le richieste successive devono includere tntId per consentire la distribuzione del contenuto corretto a un dispositivo utilizzato dallo stesso utente.

La seguente chiamata di esempio dimostra una situazione in cui tntId non viene passato a Target.

const TargetClient = require("@adobe/target-nodejs-sdk");

const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};

const targetClient = TargetClient.create(CONFIG);

targetClient.getOffers({
  request: {
    execute: {
      mboxes: [{
        name: "some-mbox"
      }]
    }
  }
})
.then(console.log)
.catch(console.error);

ClientConfig config = ClientConfig.builder()
  .client("acmeclient")
  .organizationId("1234567890@AdobeOrg")
  .build();
TargetClient targetClient = TargetClient.create(config);

Context context = new Context().channel(ChannelType.WEB);
MboxRequest mbox = new MboxRequest()
  .name("some-mbox")
  .index(0);
ExecuteRequest executeRequest = new ExecuteRequest()
  .mboxes(Arrays.asList(mbox));

TargetDeliveryRequest request = TargetDeliveryRequest.builder()
  .context(context)
  .execute(executeRequest)
  .build();

TargetDeliveryResponse offers = targetClient.getOffers(request);

In assenza di un tntId, Adobe Target genera un tntId e lo fornisce nella risposta, come segue.

{
  "status": 200,
  "requestId": "5b586f83-890c-46ae-93a2-610b1caa43ef",
  "client": "acmeclient",
  "id": {
      "tntId": "10abf6304b2714215b1fd39a870f01afc.35_0"
  },
  "edgeHost": "mboxedge35.tt.omtrdc.net",
  ...
}

In questo esempio tntId generato è 10abf6304b2714215b1fd39a870f01afc.35_0. Nota: tntId deve essere utilizzato per lo stesso utente in più sessioni.

ID di terze parti (thirdPartyId)

Se l'organizzazione utilizza un ID per identificare il visitatore, è possibile utilizzare thirdPartyID per distribuire il contenuto. Un thirdPartyID è un ID persistente utilizzato dalla tua azienda per identificare un utente finale, indipendentemente dal fatto che interagisca con la tua azienda dai canali web, mobili o IoT. In altre parole, thirdPartyId fa riferimento ai dati del profilo utente che possono essere utilizzati nei diversi canali. È tuttavia necessario fornire thirdPartyID per ogni chiamata API di consegna Adobe Target effettuata.

La chiamata di esempio seguente illustra l'utilizzo di thirdPartyId.

const TargetClient = require("@adobe/target-nodejs-sdk");

const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};

const targetClient = TargetClient.create(CONFIG);

targetClient.getOffers({
  request: {
    id: {
      thirdPartyId: "B234A029348"
    },
    execute: {
      mboxes: [{
        name: "some-mbox"
      }]
    }
  }
})
.then(console.log)
.catch(console.error);

ClientConfig config = ClientConfig.builder()
  .client("acmeclient")
  .organizationId("1234567890@AdobeOrg")
  .build();
TargetClient targetClient = TargetClient.create(config);

VisitorId id = new VisitorId()
  .thirdPartyId("B234A029348");
Context context = new Context().channel(ChannelType.WEB);
MboxRequest mbox = new MboxRequest()
  .name("some-mbox")
  .index(0);
ExecuteRequest executeRequest = new ExecuteRequest()
  .mboxes(Arrays.asList(mbox));

TargetDeliveryRequest request = TargetDeliveryRequest.builder()
  .context(context)
  .execute(executeRequest)
  .build();

TargetDeliveryResponse offers = targetClient.getOffers(request);

In questo scenario, Adobe Target genererà un tntId poiché non è stato passato nella chiamata originale, che verrà mappato al thirdPartyId fornito.

ID visitatore Marketing Cloud (marketingCloudVisitorId)

marketingCloudVisitorId è un ID universale e costante che identifica i visitatori in tutte le soluzioni di Adobe Experience Cloud. Quando l'organizzazione implementa il servizio ID, questo ID consente di identificare lo stesso visitatore del sito e i relativi dati in diverse soluzioni di Experience Cloud, tra cui Adobe Target, Adobe Analytics e Adobe Audience Manager. Si noti che marketingCloudVisitorId è obbligatorio per l'integrazione di Target con Adobe Analytics e Adobe Audience Manager.

La seguente chiamata di esempio dimostra come un marketingCloudVisitorId recuperato dal servizio ID Experience Cloud viene passato a Target.

const TargetClient = require("@adobe/target-nodejs-sdk");

const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};

const targetClient = TargetClient.create(CONFIG);

targetClient.getOffers({
  request: {
    id: {
      marketingCloudVisitorId: "10527837386392355901041112038610706884"
    },
    execute: {
      mboxes: [{
        name: "some-mbox"
      }]
    }
  }
})
.then(console.log)
.catch(console.error);

ClientConfig config = ClientConfig.builder()
  .client("acmeclient")
  .organizationId("1234567890@AdobeOrg")
  .build();
TargetClient targetClient = TargetClient.create(config);

VisitorId id = new VisitorId()
  .marketingCloudVisitorId("10527837386392355901041112038610706884");
Context context = new Context().channel(ChannelType.WEB);
MboxRequest mbox = new MboxRequest()
  .name("some-mbox")
  .index(0);
ExecuteRequest executeRequest = new ExecuteRequest()
  .mboxes(Arrays.asList(mbox));

TargetDeliveryRequest request = TargetDeliveryRequest.builder()
  .context(context)
  .execute(executeRequest)
  .build();

TargetDeliveryResponse offers = targetClient.getOffers(request);

In questo scenario, Target genererà un tntId poiché non è stato passato nella chiamata originale, che verrà mappato al marketingCloudVisitorId fornito.

ID cliente (customerIds)

Gli ID cliente possono essere aggiunti o associati a un ID visitatore di Experience Cloud. Ogni volta che si invia customerIds, è necessario specificare anche marketingCloudVisitorId. Inoltre, è possibile fornire uno stato di autenticazione insieme a ogni customerId per ogni visitatore. È possibile utilizzare i seguenti stati di autenticazione:

Stato di autenticazione	Stato dell'utente
`unknown`	Utente sconosciuto o mai autenticato. Questo stato può essere utilizzato per scenari come quello in cui un visitatore arriva sul sito facendo clic su un annuncio pubblicitario.
`authenticated`	Al momento l'utente è autenticato con una sessione attiva sul sito Web o sull'app.
`logged_out`	L'utente si è autenticato ma si è disconnesso in modo attivo. L'utente intendeva disconnettersi dallo stato autenticato. L'utente non desidera più essere trattato come utente autenticato.

Tieni presente che solo quando customerId è in uno stato autenticato Target farà riferimento ai dati del profilo utente memorizzati e collegati al customerId. Se customerId è in uno stato sconosciuto o logged_out, verrà ignorato e tutti i dati del profilo utente eventualmente associati a tale customerId non verranno utilizzati per il targeting del pubblico.

const TargetClient = require("@adobe/target-nodejs-sdk");

const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};

const targetClient = TargetClient.create(CONFIG);

targetClient.getOffers({
  request: {
    id: {
      marketingCloudVisitorId : "10527837386392355901041112038610706884",
      customerIds: [{
        id: "134325423",
        integrationCode : "crm_data",
        authenticatedState : "authenticated"
      }]
    },
    execute: {
      mboxes: [{
        name: "some-mbox"
      }]
    }
  }
})
.then(console.log)
.catch(console.error);

ClientConfig config = ClientConfig.builder()
  .client("acmeclient")
  .organizationId("1234567890@AdobeOrg")
  .build();
TargetClient targetClient = TargetClient.create(config);

CustomerId customerId = new CustomerId()
  .id("134325423")
  .integrationCode("crm_data")
  .authenticatedState(AuthenticatedState.AUTHENTICATED);
VisitorId id = new VisitorId()
  .marketingCloudVisitorId("10527837386392355901041112038610706884")
  .customerIds(Arrays.asList(customerId));
Context context = new Context().channel(ChannelType.WEB);
MboxRequest mbox = new MboxRequest()
  .name("some-mbox")
  .index(0);
ExecuteRequest executeRequest = new ExecuteRequest()
  .mboxes(Arrays.asList(mbox));

TargetDeliveryRequest request = TargetDeliveryRequest.builder()
  .context(context)
  .execute(executeRequest)
  .build();

TargetDeliveryResponse offers = targetClient.getOffers(request);

L'esempio precedente illustra come inviare un customerId con un authenticatedState. Quando si invia un customerId, sono necessari integrationCode, id e authenticatedState e marketingCloudVisitorId. integrationCode è l'alias del file degli attributi del cliente fornito tramite CRS.

Profilo unito

È possibile combinare tntId, thirdPartyID e marketingCloudVisitorId nella stessa richiesta. In questo scenario, Adobe Target manterrà la mappatura di tutti questi ID e lo fisserà a un visitatore. Scopri come unire e sincronizzare in tempo reale i profili utilizzando i diversi identificatori.

const TargetClient = require("@adobe/target-nodejs-sdk");

const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};

const targetClient = TargetClient.create(CONFIG);

targetClient.getOffers({
  request: {
    id: {
      tntId: "d359234570e044f14e1faeeba02d6ab23439914e.35_0",
      thirdPartyId: "B234A029348",
      marketingCloudVisitorId : "10527837386392355901041112038610706884"
    },
    execute: {
      mboxes: [{
        name: "some-mbox"
      }]
    }
  }
})
.then(console.log)
.catch(console.error);

ClientConfig config = ClientConfig.builder()
  .client("acmeclient")
  .organizationId("1234567890@AdobeOrg")
  .build();
TargetClient targetClient = TargetClient.create(config);

VisitorId id = new VisitorId()
  .tntId("d359234570e044f14e1faeeba02d6ab23439914e.35_0")
  .thirdPartyId("B234A029348")
  .marketingCloudVisitorId("10527837386392355901041112038610706884");
Context context = new Context().channel(ChannelType.WEB);
MboxRequest mbox = new MboxRequest()
  .name("some-mbox")
  .index(0);
ExecuteRequest executeRequest = new ExecuteRequest()
  .mboxes(Arrays.asList(mbox));

TargetDeliveryRequest request = TargetDeliveryRequest.builder()
  .context(context)
  .execute(executeRequest)
  .build();

TargetDeliveryResponse offers = targetClient.getOffers(request);

L'esempio precedente illustra come combinare tntId, thirdPartyID e marketingCloudVisitorId nella stessa richiesta.

Bucket

Gli utenti sono inseriti nel gruppo di visualizzazione di un'esperienza in base alla configurazione delle attività di Adobe Target. In Adobe Target, bucket è:

Deterministico: MurmurHash3 viene utilizzato per garantire che l'utente sia inserito nel bucket e veda la giusta variante ogni volta, purché l'ID utente sia coerente.
Sticky: Adobe Target memorizza la variante visualizzata dall'utente nel profilo utente per garantire che la variante venga mostrata in modo coerente all'utente in tutte le sessioni e i canali. Le varianti e la fedeltà sono garantite quando si utilizzano decisioni lato server. Quando si utilizzano decisioni su dispositivo, la fedeltà non è garantita.

Flusso di lavoro di bucket end-to-end

Prima di immergerti nell’algoritmo di bucket effettivo, è importante sottolineare che passaggi simili vengono utilizzati sia per selezionare le attività in base alla loro percentuale di allocazione del traffico, sia per selezionare un’esperienza all’interno di un’attività.

Passaggi per la selezione di attività

Generare un ID dispositivo, in genere un UUID
Ottieni il codice client
Ottieni l’ID attività
Prendi il sale, che di solito è una stringa come "attività"
Calcola l’hash utilizzando MurmurHash3
Ottieni il valore assoluto dell’hash
Dividi il valore assoluto dell’hash per 10000
Dividere il resto per 10000, che dovrebbe produrre un valore compreso tra 0 e 1
Moltiplica il risultato per 100%
Confronta la percentuale di allocazione del traffico dell’attività con la percentuale ottenuta. Se la percentuale di allocazione del traffico è inferiore, l’attività viene selezionata. In caso contrario, l’attività viene saltata.

Passaggi per la selezione dell’esperienza

Generare un ID dispositivo, in genere un UUID
Ottieni il codice client
Ottieni l’ID attività
Prendi il sale, che di solito è una stringa come "esperienza"
Calcola l’hash utilizzando MurmurHash3
Ottieni il valore assoluto dell’hash
Dividi il valore assoluto dell’hash per 10000
Dividere il resto per 10000, che dovrebbe produrre un valore compreso tra 0 e 1
Moltiplica il risultato per il numero totale di esperienze all’interno dell’attività
Arrotondare il risultato. Questo dovrebbe produrre l’indice dell’esperienza.

Esempio

Si supponga quanto segue:

Client C con codice client acmeclient
Attività A con ID 1111 e tre esperienze E1, E2, E3
Le esperienze hanno la seguente distribuzione: E1 - 33%, E2 - 33%, E3 - 34%

Il flusso di selezione si presenta così:

ID dispositivo 702ff4d0-83b1-4e2e-a0a6-22cbe460eb15
Codice client acmeclient
ID attività 1111
Sale experience
Valore da hash acmeclient.1111.702ff4d0-83b1-4e2e-a0a6-22cbe460eb15.experience, valore hash -919077116
Valore assoluto dell'hash 919077116
Rimanente dopo la divisione per 10000, 7116
Il valore dopo il resto è diviso per 10000, 0.7116
Risultato dopo la moltiplicazione del valore per il numero totale di esperienze 3 * 0.7116 = 2.1348
L'indice di esperienza è 2, ovvero la terza esperienza, poiché viene utilizzata l'indicizzazione basata su 0.

recommendation-more-help