Rastrear eventos

Para enviar dados do evento para o Adobe Experience Cloud, use o comando sendEvent. O comando sendEvent é a maneira principal de enviar dados para o Experience Cloud e recuperar conteúdo personalizado, identidades e destinos de público-alvo.

Os dados enviados para o Adobe Experience Cloud são divididos em duas categorias:

  • Dados XDM
  • Dados não XDM

Envio de dados XDM

Os dados XDM são um objeto cujo conteúdo e estrutura correspondem a um esquema criado no Adobe Experience Platform. Saiba mais sobre como criar um schema.

Quaisquer dados XDM que você deseja que façam parte de sua análise, personalização, públicos-alvo ou destinos devem ser enviados usando a opção xdm.

alloy("sendEvent", {
  "xdm": {
    "commerce": {
      "order": {
        "purchaseID": "a8g784hjq1mnp3",
        "purchaseOrderNumber": "VAU3123",
        "currencyCode": "USD",
        "priceTotal": 999.98
      }
    }
  }
});

Pode passar algum tempo entre a execução do comando sendEvent e o envio dos dados para o servidor (por exemplo, se a biblioteca do SDK da Web não tiver sido totalmente carregada ou o consentimento ainda não tiver sido recebido). Se você pretende modificar qualquer parte do objeto xdm após executar o comando sendEvent, é altamente recomendável clonar o objeto xdm antes de executar o comando sendEvent. Por exemplo:

var clone = function(value) {
  return JSON.parse(JSON.stringify(value));
};

var dataLayer = {
  "commerce": {
    "order": {
      "purchaseID": "a8g784hjq1mnp3",
      "purchaseOrderNumber": "VAU3123",
      "currencyCode": "USD",
      "priceTotal": 999.98
    }
  }
};

alloy("sendEvent", {
  "xdm": clone(dataLayer)
});

// This change will not be reflected in the data sent to the 
// server for the prior sendEvent command.
dataLayer.commerce = null;

Neste exemplo, a camada de dados é clonada serializando-a para JSON e depois desserializando-a. Em seguida, o resultado clonado é transmitido ao comando sendEvent. Isso garante que o comando sendEvent tenha um instantâneo da camada de dados como existia quando o comando sendEvent foi executado, de modo que modificações posteriores no objeto da camada de dados original não sejam refletidas nos dados enviados para o servidor. Se você estiver usando uma camada de dados orientada por eventos, a clonagem de seus dados provavelmente já será manipulada automaticamente. Por exemplo, se estiver usando a Camada de dados do cliente do Adobe, o método getState() fornecerá um instantâneo computado e clonado de todas as alterações anteriores. Isso também é feito para você automaticamente se estiver usando a extensão de tag Adobe Experience Platform Web SDK.

OBSERVAÇÃO

Há um limite de 32 KB nos dados que podem ser enviados em cada evento no campo XDM.

Envio de dados não XDM

Os dados que não correspondem a um esquema XDM devem ser enviados usando a opção data do comando sendEvent. Esse recurso é compatível com versões 2.5.0 e posteriores do SDK da Web.

Isso é útil se você precisar atualizar um perfil do Adobe Target ou enviar atributos do Recommendations do Target. Leia mais sobre esses recursos do Target.

No futuro, você poderá enviar a camada de dados completa sob a opção data e mapeá-la para o lado do servidor XDM.

Como enviar atributos do Perfil e do Recommendations para o Adobe Target:

alloy("sendEvent", {
  data: {
    __adobe: {
      target: {
        "profile.gender": "female",
        "profile.age": 30,
        "entity.id" : "123",
        "entity.genre" : "Drama"
      }
    }
  }
});

Configuração eventType

Em esquemas XDM ExperienceEvent, há um campo opcional eventType. Isso mantém o tipo de evento principal para o registro. Definir um tipo de evento pode ajudar você a diferenciar os diferentes eventos que serão enviados. O XDM fornece vários tipos de evento predefinidos que podem ser usados ou você sempre cria seus próprios tipos de evento personalizados para seus casos de uso. Consulte a documentação XDM para obter uma lista de todos os tipos de evento predefinidos.

Esses tipos de evento serão mostrados em uma lista suspensa se você estiver usando a extensão de tag ou sempre puder transmiti-los sem tags. Eles podem ser transmitidos como parte da opção xdm .

alloy("sendEvent", {
  "xdm": {
    "eventType": "commerce.purchases",
    "commerce": {
      "order": {
        "purchaseID": "a8g784hjq1mnp3",
        "purchaseOrderNumber": "VAU3123",
        "currencyCode": "USD",
        "priceTotal": 999.98
      }
    }
  }
});

Como alternativa, o eventType pode ser passado para o comando event usando a opção type. Em segundo plano, isso é adicionado aos dados XDM. Ter o type como uma opção permite definir mais facilmente o eventType sem precisar modificar a carga do XDM.

var myXDMData = { ... };

alloy("sendEvent", {
  "xdm": myXDMData,
  "type": "commerce.purchases"
});

Substituição da ID do conjunto de dados

Em alguns casos de uso, você pode enviar um evento para um conjunto de dados diferente daquele configurado na interface do usuário de configuração. Para isso, é necessário definir a opção datasetId no comando sendEvent:

var myXDMData = { ... };

alloy("sendEvent", {
  "xdm": myXDMData,
  "type": "commerce.checkout",
  "datasetId": "YOUR_DATASET_ID"
});

Adição de informações de identidade

As informações de identidade personalizadas também podem ser adicionadas ao evento. Consulte Recuperando Experience Cloud ID.

Uso da API sendBeacon

Pode ser complicado enviar dados de evento antes que o usuário da página da Web tenha saído. Se a solicitação demorar muito, o navegador pode cancelar a solicitação. Alguns navegadores implementaram uma API padrão da Web chamada sendBeacon para permitir que os dados sejam coletados com mais facilidade durante esse período. Ao usar sendBeacon, o navegador faz a solicitação da Web no contexto de navegação global. Isso significa que o navegador faz a solicitação de beacon em segundo plano e não segura a navegação da página. Para dizer ao Adobe Experience Platform Web SDK para usar sendBeacon, adicione a opção "documentUnloading": true ao comando event. Exemplo:

alloy("sendEvent", {
  "documentUnloading": true,
  "xdm": {
    "commerce": {
      "order": {
        "purchaseID": "a8g784hjq1mnp3",
        "purchaseOrderNumber": "VAU3123",
        "currencyCode": "USD",
        "priceTotal": 999.98
      }
    }
  }
});

Os navegadores impuseram limites para a quantidade de dados que pode ser enviada com sendBeacon de uma vez. Em muitos navegadores, o limite é de 64 K. Se o navegador rejeitar o evento porque a carga é muito grande, o Adobe Experience Platform Web SDK voltará a usar seu método de transporte normal (por exemplo, busca).

Lidar com respostas de eventos

Se quiser lidar com uma resposta de um evento, você poderá ser notificado de um sucesso ou falha da seguinte maneira:

alloy("sendEvent", {
  "renderDecisions": true,
  "xdm": {
    "commerce": {
      "order": {
        "purchaseID": "a8g784hjq1mnp3",
        "purchaseOrderNumber": "VAU3123",
        "currencyCode": "USD",
        "priceTotal": 999.98
      }
    }
  }
}).then(function(results) {
    // Tracking the event succeeded.
  })
  .catch(function(error) {
    // Tracking the event failed.
  });

Modificação global de eventos

Se quiser adicionar, remover ou modificar campos do evento globalmente, você pode configurar um retorno de chamada onBeforeEventSend. Esse retorno de chamada é chamado sempre que um evento é enviado. Esse retorno de chamada é passado em um objeto de evento com um campo xdm. Modifique content.xdm para alterar os dados enviados com o evento.

alloy("configure", {
  "edgeConfigId": "ebebf826-a01f-4458-8cec-ef61de241c93",
  "orgId": "ADB3LETTERSANDNUMBERS@AdobeOrg",
  "onBeforeEventSend": function(content) {
    // Change existing values
    content.xdm.web.webPageDetails.URL = xdm.web.webPageDetails.URL.toLowerCase();
    // Remove existing values
    delete content.xdm.web.webReferrer.URL;
    // Or add new values
    content.xdm._adb3lettersandnumbers.mycustomkey = "value";
  }
});

xdm são definidos nesta ordem:

  1. Valores passados como opções para o comando de evento alloy("sendEvent", { xdm: ... });
  2. Valores coletados automaticamente. (Consulte Informações Automáticas.)
  3. As alterações feitas no retorno de chamada onBeforeEventSend.

Algumas observações sobre o retorno de chamada onBeforeEventSend:

  • O XDM do evento pode ser modificado durante o retorno de chamada. Depois que a chamada de retorno for retornada, todos os campos e valores modificados de
    os objetos content.xdm e content.data são enviados com o evento .

    onBeforeEventSend: function(content){
  //sets a query parameter in XDM
  const queryString = window.location.search;
  const urlParams = new URLSearchParams(queryString);
  content.xdm.marketing.trackingCode = urlParams.get('cid')
}

  • Se o retorno de chamada gerar uma exceção, o processamento do evento será interrompido e o evento não será enviado.

  • Se o retorno de chamada retornar o valor booleano de false, o processamento de evento será interrompido,
    sem um erro e o evento não é enviado. Esse mecanismo permite que determinados eventos sejam facilmente ignorados por
    examinando os dados do evento e retornando false se o evento não deve ser enviado.

    OBSERVAÇÃO

    Deve-se tomar cuidado para evitar retornar "false" no primeiro evento em uma página. Retornar false no primeiro evento pode afetar negativamente a personalização.

   onBeforeEventSend: function(content) {
     // ignores events from bots
     if (MyBotDetector.isABot()) {
       return false;
     }
   }

Qualquer valor de retorno diferente do booleano false permitirá que o evento processe e envie após o retorno de chamada.

  • Os eventos podem ser filtrados examinando o tipo de evento (Consulte Tipos de evento.):
    onBeforeEventSend: function(content) {  
      // augments XDM if link click event is to a partner website
      if (
        content.xdm.eventType === "web.webinteraction.linkClicks" &&
        content.xdm.web.webInteraction.URL ===
          "http://example.com/partner-page.html"
      ) {
        content.xdm.partnerWebsiteClick = true;
      }
   }

Possíveis erros acionáveis

Ao enviar um evento, um erro pode ser lançado se os dados que estão sendo enviados forem muito grandes (mais de 32 KB para a solicitação completa). Nesse caso, é necessário reduzir a quantidade de dados que estão sendo enviados.

Nesta página