Entregar ofertas usando a API de decisão decisioning-api

Com a Gestão de decisões, você pode criar e fornecer experiências de oferta personalizada de usuários finais, em canais e aplicativos usando lógica de negócios e regras de decisão. Uma oferta é uma mensagem de marketing que pode ter regras associadas que especificam quem está qualificado para ver a oferta.

Você pode criar e entregar ofertas fazendo uma solicitação POST à Decisioning API.

Este tutorial requer uma compreensão funcional das APIs, especificamente no que diz respeito à Gestão de decisões. Para obter mais informações, consulte Guia do desenvolvedor da API de Gestão de decisões. Este tutorial também requer que você tenha uma ID de posicionamento exclusiva e um valor de ID de decisão disponíveis. Se você não adquiriu esses valores, consulte os tutoriais do criação de uma inserção e criação de uma decisão.

➡️ Descubra este recurso no vídeo

Cabeçalhos obrigatórios required-headers

A tabela a seguir mostra os valores válidos que compõem a variável Tipo de conteúdo e Aceitar campos no cabeçalho da solicitação:

Nome do cabeçalho
Valor
Aceitar
application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"
Tipo de conteúdo
application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0"
Autorização
Bearer {ACCESS_TOKEN}
x-gw-ims-org-id
{IMS_ORG}
x-sandbox-name
{SANDBOX_NAME}
x-api-key
{API_KEY}
  • Todas as solicitações que contêm uma carga (POST,PUT,PATCH) exigem o cabeçalho de tipo de conteúdo

solicitação de API request

Formato da API

POST /{ENDPOINT_PATH}/decisions
Parâmetro
Descrição
Exemplo
{ENDPOINT_PATH}
O caminho do endpoint para APIs do repositório.
https://platform.adobe.io/data/core/ods
{CONTAINER_ID}
O contêiner onde as decisões estão localizadas.
e0bd8463-0913-4ca1-bd84-6309134ca1f6

Solicitação

curl -X POST \
  'https://platform.adobe.io/data/core/ods/decisions' \
  -H 'Accept: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-response;version=1.0"' \
  -H 'Content-Type: application/vnd.adobe.xdm+json; schema="https://ns.adobe.com/experience/offer-management/decision-request;version=1.0"'
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
        "xdm:propositionRequests": [
            {
              "xdm:placementId": "xcore:offer-placement:ffed0456",
              "xdm:activityId": "xcore:offer-activity:ffed0123",
              "xdm:itemCount": 2
            },
            {
              "xdm:placementId": "xcore:offer-placement:ffed0012",
              "xdm:activityId": "xcore:offer-activity:fffc0789"
            }
        ],
        "xdm:profiles": [
            {
              "xdm:identityMap": {
                "SWCUSTID": [
                {
                    "xdm:id": "123@abc.com"
                }
                ]
            },
            "xdm:decisionRequestId": "0AA00002-0000-1224-c0de-cjf98Csj43"
            }
        ],
        "xdm:allowDuplicatePropositions": {
            "xdm:acrossActivities": true,
            "xdm:acrossPlacements": true
        },
        "xdm:mergePolicy": {
            "xdm:id": "5f3ed32f-eaf1-456c-b0f0-7b338c4cb18a"
        },
        "xdm:responseFormat": {
            "xdm:includeContent": true,
            "xdm:includeMetadata": {
            "xdm:activity": [
                "name"
            ],
            "xdm:option": [
                "name"
            ],
            "xdm:placement": [
                "name"
            ]
            }
        }
      }'
Propriedade
Descrição
Exemplo
xdm:propositionRequests
Esse objeto contém os identificadores de posicionamento e decisão.
xdm:propositionRequests.xdm:placementId
O identificador de posicionamento exclusivo.
"xdm:placementId": "xcore:offer-placement:ffed0456"
xdm:propositionRequests.xdm:activityId
O identificador de decisão exclusivo.
"xdm:activityId": "xcore:offer-activity:ffed0123"
xdm:itemCount
O número de ofertas a serem retornadas. O número máximo é 30.
"xdm:itemCount": 2
xdm:profiles
Esse objeto mantém informações sobre o perfil para o qual a decisão é solicitada. Para uma solicitação de API, ela conterá um perfil.
xdm:profiles.xdm:identityMap
Esse objeto mantém um conjunto de identidades de usuário final com base no código de integração de namespace da identidade. O mapa de identidade pode conter mais de uma identidade de cada namespace. Para obter mais informações sobre namespaces, consulte esta página.
Email: [{"xdm:id": "123@abc.com"}]
xdm:profiles.xdm:decisionRequestId
A ID gerada pelo cliente que pode ser usada para identificar exclusivamente uma solicitação de decisão de perfil. Essa ID é retomada na resposta do e não influencia o resultado da decisão.
"xdm:decisionRequestId": "0AA00002-0000-1224-c0de-cjf98Csj43"
xdm:allowDuplicatePropositions
Esse objeto controla a estrutura das regras de desduplicação. Consiste em uma série de sinalizadores que indicam se a mesma opção pode ser proposta através de uma determinada dimensão. Um sinalizador definido como verdadeiro significa que duplicatas são permitidas e não devem ser removidas na categoria indicada pelo sinalizador. Um sinalizador definido como falso significa que o mecanismo de decisão não deve fazer a mesma proposta na dimensão e, em vez disso, escolher a próxima melhor opção para uma das subdecisões.
xdm:allowDuplicatePropositions.xdm:acrossActivities
Se definido como verdadeiro, várias decisões podem receber a mesma opção.
"xdm:acrossActivities": true
xdm:allowDuplicatePropositions.xdm:acrossPlacements
Se definido como verdadeiro, vários posicionamentos podem receber a mesma opção.
"xdm:acrossPlacements": true
xdm:mergePolicy.xdm:id
Identifica a política de mesclagem pela qual controlar os dados retornados pelo serviço de acesso ao perfil. Se um não for especificado na solicitação, o Gerenciamento de decisões não transmitirá nenhum serviço de acesso de perfil, caso contrário, transmitirá a ID fornecida pelo chamador.
"xdm:id": "5f3ed32f-eaf1-456c-b0f0-7b338c4cb18a"
xdm:responseFormat
Um conjunto de sinalizadores que formata o conteúdo da resposta.
xdm:responseFormat.xdm:includeContent
Um valor booleano que, se definido como true, inclui conteúdo na resposta.
"xdm:includeContent": true
xdm:responseFormat.xdm:includeMetadata
Um objeto usado para especificar quais metadados adicionais são retornados. Se essa propriedade não for incluída, xdm:id e repo:etag são retornados por padrão.
name
xdm:responseFormat.xdm:activity
Esse sinalizador identifica as informações de metadados específicas retornadas para xdm:activity.
name
xdm:responseFormat.xdm:option
Esse sinalizador identifica as informações de metadados específicas retornadas para xdm:option.
name, characteristics
xdm:responseFormat.xdm:placement
Esse sinalizador identifica as informações de metadados específicas retornadas para xdm:placement.
name, channel, componentType

Resposta

Uma resposta bem-sucedida retorna informações sobre sua proposta, incluindo suas xdm:propositionId.

{
  "xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8",
  "xdm:propositions": [
    {
      "xdm:activity": {
        "xdm:id": "xcore:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "xcore:placement:ffed0456",
        "repo:etag": 1
      },
      "xdm:options": [
        {
          "xdm:id": "xcore:personalized-option:ccc0111",
          "repo:etag": 3,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>some html</html>"
        },
        {
          "xdm:id": "xcore:personalized-option:ccc0222",
          "repo:etag": 5,
          "@type": "https://ns.adobe.com/experience/decisioning/content-component-html-template",
          "xdm:content": "<html>hello, world</html>",
          "xdm:score": 45.65
        }
      ]
    },
    {
      "xdm:activity": {
        "xdm:id": "xcore:activity:ffed0123",
        "repo:etag": 4
      },
      "xdm:placement": {
        "xdm:id": "xcore:placement:ffed0789",
        "repo:etag": 2
      },
      "xdm:fallback": {
        "xdm:id": "xcore:fallback:ccc0222",
        "repo:etag": 5,
        "@type": "https://ns.adobe.com/experience/decisioning/content-component-imagelink",
        "dc:format": "image/png",
        "xdm:deliveryURL": "https://cdn.adobe.com/content/1445323-1134331.png",
        "xdm:content": "https://www.adobe.com/index2.html"
      }
    }
  ],
  "ode:createDate": 1566497582038
}
Propriedade
Descrição
Exemplo
xdm:propositionId
O identificador exclusivo da entidade de proposta associada a um XDM DecisionEvent.
"xdm:propositionId": "5d0ffb5e-dfc6-4280-99b6-0bf3131cb8b8"
xdm:propositions
Esse objeto contém uma única apresentação de decisão. Várias opções podem ser retornadas para a decisão. Se nenhuma opção for encontrada, a oferta de fallback da decisão será retornada. As propostas de decisão únicas sempre incluem um options propriedade ou um fallback propriedade. Quando presente, a variável options a propriedade não pode estar vazia.
xdm:propositions.xdm:activity
Este objeto contém o identificador exclusivo de uma decisão.
"xdm:id": "xcore:activity:ffed0123"
xdm:propositions.xdm:placement
Este objeto contém o identificador exclusivo para uma disposição de oferta.
"xdm:id": "xcore:placement:ffed0456"
xdm:propositions.xdm:options
Este objeto contém uma única opção, incluindo seu identificador exclusivo. Se presente, esse objeto não pode estar vazio.
xdm:id": "xcore:personalized-option:ccc0111
xdm:propositions.xdm:options.@type
Define o tipo do componente. @type atua como o contrato de processamento do cliente. Quando a experiência for montada, o compositor procurará os componentes que tenham um tipo específico.
https://ns.adobe.com/experience/offer-management/content-component-imagelink
xdm:propositions.xdm:content
O formato do conteúdo da resposta.
O conteúdo da resposta pode ser: text, html blockou image link
xdm:score
A pontuação de uma opção que é calculada como resultado de uma função de classificação associada à opção ou à decisão. Esse campo será retornado pela API se uma função de classificação estiver envolvida na determinação da pontuação de uma oferta durante a classificação.
"xdm:score": 45.65
xdm:propositions.xdm:fallback
Esse objeto contém uma única oferta substituta, incluindo seu identificador exclusivo.
"xdm:id": "xcore:fallback:ccc0222"
xdm:propositions.xdm:fallback.dc:format
A manifestação física ou digital do recurso. Normalmente, o formato deve incluir o tipo de mídia do recurso. O formato pode ser usado para determinar o software, hardware ou outro equipamento necessário para exibir ou operar o recurso. É recomendável selecionar um valor de um vocabulário controlado, por exemplo, a lista de Tipos de mídia da Internet definindo formatos de mídia de computador.
"dc:format": "image/png" ou "image/jpeg"
xdm:propositions.xdm:fallback.xdm:deliveryURL
Um URL opcional para ler o ativo de uma rede de entrega de conteúdo ou ponto de extremidade de serviço. Esse URL é usado para acessar o ativo publicamente de um agente do usuário.
https://d37yhxrr0p3l3l.cloudfront.net/0fd0f090-a148-11ea-89e3-f1f2ad52f7e8/urn:aaid:sc:US:a68c86a6-9295-4940-a083-11916b665500/0/40d78a12-f8b6-3f07-8e67-7cb8ae2cc7ec
ode:createDate
A hora em que a mensagem de resposta de decisão foi criada. Isso é representado como época.
"ode:createDate": 1566497582038

Códigos de resposta

A tabela abaixo lista todos os códigos que podem ser retornados na resposta:

Código
Descrição
200
Sucesso. A decisão foi tomada para determinadas atividades
400
Parâmetro de solicitação inválido. A solicitação não pode ser entendida pelo servidor devido à sintaxe malformada.
403
Proibido, permissões insuficientes.
422
Entidade não processável. A sintaxe da solicitação está correta, no entanto, devido a erros semânticos, ela não pode ser processada.
429
Muitas solicitações. O usuário enviou muitas solicitações em um determinado período.
500
Erro interno do servidor. O servidor encontrou uma condição inesperada que o impediu de atender à solicitação.
503
Serviço indisponível devido à sobrecarga do servidor. No momento, o servidor não pode lidar com a solicitação devido a uma sobrecarga temporária.

Próximas etapas next-steps

Ao seguir este guia de API, você criou e entregou ofertas usando o Decisions API. Para obter mais informações, consulte visão geral do Gerenciamento de decisão.

recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76