Pular para o conteúdo principal

​
Visão geral

​
Introdução

Os testes A/B permitem que anunciantes segmentem os usuários que alcançam no X, para entender como otimizar da melhor forma o desempenho da campanha e extrair aprendizados que orientem suas estratégias de marketing. Esses segmentos — chamados de divisões de grupos de usuários — são aleatórios e mutuamente exclusivos. Com a aleatorização, os fatores que influenciam os resultados ficam distribuídos de forma equilibrada. Em outras palavras, não há diferenças inerentes entre os grupos nem em seus comportamentos esperados. Por isso, quando uma única variação é aplicada a um grupo de usuários e não aos outros, a diferença no desempenho da campanha pode ser atribuída a essa variação. Embora seja possível testar várias variações ao mesmo tempo, recomendamos fortemente testar apenas uma variação por vez. Isso isola o fator causal da diferença observada no desempenho da campanha. As variações são definidas no nível da campanha. Por exemplo, se o anunciante quiser testar a eficácia de um novo criativo, deverá criar duas campanhas idênticas em que a única diferença seja o criativo. No futuro, planejamos oferecer suporte a variações no nível do item.

​
Casos de uso

O teste A/B é mais frequentemente utilizado para: (1) casos de otimização, voltados a clientes de performance que desejam entender o que funciona melhor no X para otimizar seus investimentos; e (2) casos de aprendizado, voltados a anunciantes de marca que desejam aplicar esses aprendizados para orientar sua estratégia de marketing. A API oferecerá suporte a testes A/B para qualquer variável de campanha, incluindo:
  • Criativo
  • Segmentação
  • Tipo de lance
  • Unidade de lance

​
Testes A/B

Os Testes A/B permitem que anunciantes segmentem os usuários que estão alcançando no X para entender como otimizar ao máximo o desempenho da campanha e obter insights que orientem suas estratégias de marketing. Esses segmentos — chamados de divisões de grupos de usuários — são aleatórios e mutuamente exclusivos. Com a aleatoriedade, os fatores que influenciam os resultados são distribuídos de forma equilibrada. Em outras palavras, não há diferenças inerentes entre os grupos nem em seus comportamentos esperados. Por isso, quando uma única variação é aplicada a um grupo de usuários e não aos demais, a diferença no desempenho da campanha pode ser atribuída a essa variação. Embora seja possível testar várias variações ao mesmo tempo, recomendamos fortemente testar uma única variação por vez. Isso isola o fator causal da diferença observada no desempenho da campanha. As variações são definidas no nível da campanha ou no nível do grupo de anúncios. O grupo de anúncios é configurado por meio de line item na X Ads API. Como exemplo de variação no nível do grupo de anúncios, se o anunciante quiser testar a eficácia de uma nova criação, ele deve criar uma campanha com 2 grupos de anúncios idênticos em que a única diferença seja a criação.

​
Casos de uso

O teste A/B é mais frequentemente usado para dar suporte a (1) casos de otimização para clientes focados em performance que desejam entender o que funciona melhor no X a fim de otimizar seus investimentos e (2) casos de aprendizado para anunciantes de marca que querem usar esses aprendizados para orientar sua estratégia de marketing. A API oferecerá suporte a testes A/B para qualquer variável de campanha, incluindo:
  • Criativo
  • Segmentação
  • Tipo de lance
  • Unidade de lance

​
Atributos

Os Testes A/B são representados como estruturas aninhadas. Há campos de nível superior para o próprio Teste A/B e um array de objetos de grupos de usuários, cada um com um conjunto de campos que o descrevem. Em alto nível, todo Teste A/B deve incluir as seguintes informações.
  • A duração do teste, representada pelos campos start_time e end_time
  • O nível em que a divisão ocorrerá, representado pelo campo entity_type
  • Pelo menos dois (e no máximo 30) grupos de usuários, cada um representado como um objeto no array user_groups
Cada grupo de usuários deve incluir as seguintes informações.
  • A porcentagem de usuários que deve ser alocada ao grupo de usuários em questão, representada pelo campo size
  • As campaign IDs/line item IDs que devem compor o conjunto de usuários para o grupo de usuários em questão, representadas pelo array entity_ids
Opcionalmente, valores de name e description podem ser definidos para Testes A/B e para grupos de usuários. Informações sobre regras de validação e outras restrições podem ser encontradas abaixo. Outros metadados, como o ID ou o horário de criação, também estão incluídos, mas são definidos automaticamente pela X. Um exemplo de entidade de Teste A/B no nível de campanha é mostrado abaixo. 
{
  "created_at": "2020-12-01T00:00:00Z",
  "created_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  },
  "deleted": false,
  "description": "exemplo de documentação",
  "end_time": "2020-12-05T01:00:00Z",
  "entity_type": "CAMPAIGN",
  "id": "hr7l0",
  "name": "primeiro teste AB",
  "start_time": "2020-12-01T01:00:00Z",
  "status": "SCHEDULED",
  "user_groups": [
    {
      "id": "p1bcx",
      "name": "primeiro grupo",
      "description": null,
      "size": "50.0",
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ]
    },
    {
      "id": "p1bcy",
      "name": "segundo grupo",
      "description": "segundo grupo de teste AB",
      "size": 50,
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ]
    }
  ],
  "updated_at": "2020-12-01T00:00:00Z",
  "updated_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  }
}
Um exemplo de entidade de teste A/B no nível de item de linha é mostrado abaixo. 
{
   "created_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "name":"Test2e",
   "start_time":"2022-08-15T00:00:00Z",
   "updated_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "description":"Meu segundo teste A/B",
   "entity_type":"LINE_ITEM",
   "end_time":"2022-08-30T00:00:00Z",
   "id":"1ul",
   "user_groups":[
      {
         "name":"primeiro grupo",
         "size":"50.0",
         "description":"descrição do primeiro grupo",
         "entity_ids":[
            "ij9dh"
         ],
         "id":"4xe"
      },
      {
         "name":"segundo grupo",
         "size":"50.0",
         "description":"descrição do segundo grupo",
         "entity_ids":[
            "ihng8"
         ],
         "id":"4xf"
      }
   ],
   "status":"SCHEDULED",
   "created_at":"2022-08-11T00:10:50Z",
   "updated_at":"2022-08-11T00:10:50Z",
   "deleted":false
}

​
Uso

As subseções abaixo explicam como criar e atualizar testes A/B. A leitura e a exclusão funcionam da mesma forma que em todos os outros endpoints da X Ads API.

​
Criação

Crie um Teste A/B usando o endpoint POST accounts/:account_id/ab_tests. O endpoint aceita apenas corpos de requisição POST em JSON. O cabeçalho Content-Type deve ser definido como application/json. Depois que o anunciante configurar duas ou mais campanhas, é possível criar um Teste A/B. Conforme mencionado acima, Testes A/B devem incluir: duração do teste, nível de divisão e pelo menos dois grupos de usuários. Cada grupo de usuários deve declarar a porcentagem de usuários que deve ser alocada a ele, bem como os IDs de campanha que comporão seu conjunto de usuários. Cada um desses itens é descrito em mais detalhes abaixo. Duração do teste:
  • Os valores de start_time e end_time devem
    • Estar no futuro (em relação ao momento em que o Teste A/B é criado)
    • Sobrepor-se às datas de veiculação da campanha/line item
  • O teste deve durar pelo menos um dia para campanhas que não sejam baseadas em app e pelo menos cinco dias para campanhas baseadas em app
Nível de divisão:
  • O entity_type pode ser definido como CAMPAIGN ou LINE_ITEM
Grupos de usuários:
  • Cada grupo de usuários é representado como um objeto no array user_groups
    • É necessário um mínimo de dois grupos de usuários
    • É permitido um máximo de 30 grupos de usuários
  • O tamanho de cada grupo de usuários é definido usando uma representação em string de um valor numérico entre 1.00 e 99.00
    • Observação: Os valores de tamanho entre objetos devem somar 100.00
  • Os IDs de campanha devem ser especificados no array entity_ids de cada grupo de usuários
Opcionalmente, defina name e description para o Teste A/B ou para um ou mais grupos de usuários. A solicitação a seguir cria um Teste A/B no nível de campanha que dura quatro dias e tem dois grupos de usuários com 50% dos usuários em cada grupo. O primeiro grupo de usuários é baseado nas campanhas f2qcw e f2tht; o segundo grupo de usuários é baseado nas campanhas f2rqi e f2tws. A solicitação também adiciona nomes e descrições a algumas partes da entidade. twurl -X POST -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests” -d ’{“end_time”: “2020-12-05T01:00:00Z”, “entity_type” : “CAMPAIGN”, “start_time”: “2020-12-01T01:00:00Z”, “user_groups”: [{“entity_ids”: [“f2qcw”, “f2tht”], “size”: “50.00”, “name”: “first group”},{“entity_ids”: [“f2rqi”, “f2tws”], “size”: “50.00”, “name”: “second group”, “description”: “second AB test group”}], “name”: “first AB test”, “description”: “documentation example”}’ 
twurl -X POST -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests" -d '{"end_time": "2020-12-05T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2020-12-01T01:00:00Z", "user_groups": [{"entity_ids": ["f2qcw", "f2tht"], "size": "50.00", "name": "first group"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "second group", "description": "second AB test group"}], "name": "first AB test", "description": "documentation example"}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "end_time": "2020-12-05T01:00:00Z",
      "entity_type": "CAMPAIGN",
      "start_time": "2020-12-01T01:00:00Z",
      "user_groups": [
        {
          "entity_ids": [
            "f2qcw",
            "f2tht"
          ],
          "size": "50.0",
          "name": "first group"
        },
        {
          "entity_ids": [
            "f2rqi",
            "f2tws"
          ],
          "size": "50.0",
          "name": "second group",
          "description": "second AB test group"
        }
      ],
      "name": "first AB test",
      "description": "documentation example"
    }
  },
  "data": {
    "created_at": "2020-12-01T00:00:00Z",
    "created_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    },
    "deleted": false,
    "description": "documentation example",
    "end_time": "2020-12-05T01:00:00Z",
    "entity_type": "CAMPAIGN",
    "id": "hr7l0",
    "name": "first AB test",
    "start_time": "2020-12-01T01:00:00Z",
    "status": "SCHEDULED",
    "user_groups": [
      {
        "id": "p1bcx",
        "name": "first group",
        "description": null,
        "size": "50.0",
        "entity_ids": [
          "f2qcw",
          "f2tht"
        ]
      },
      {
        "id": "p1bcy",
        "name": "second group",
        "description": "second AB test group",
        "size": "50.0",
        "entity_ids": [
          "f2rqi",
          "f2tws"
        ]
      }
    ],
    "updated_at": "2020-12-01T00:00:00Z",
    "updated_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    }
  }
}
Para testes A/B no nível de line item A principal diferença entre testes A/B nos níveis de campanha e de line item é o entity_type. Precisamos defini-lo como ‘entity_type’ = ‘LINE_ITEM’ para testes A/B no nível de line item. Isso se aplica a todas as ações em um teste A/B já criado abaixo. Requisitos:
  1. Todos os line items da campanha de teste A/B devem ser incluídos no split test.
  2. Somente divisão igual é permitida no nível de line item.
  3. O número de line items de grupos de usuários permitido em 1 split test deve ser menor ou igual a 5.
  4. Apenas 1 line item por grupo de usuários.

​
Atualizando

Atualize um Teste A/B usando o endpoint PUT accounts/:account_id/ab_tests/:ab_test_id. O endpoint exige que um blob JSON seja enviado na solicitação. O Content-Type deve ser definido como application/json. Como outros endpoints de atualização, o endpoint PUT accounts/:account_id/ab_tests/:ab_test_id exige que o ID do Teste A/B seja referenciado na URL. Em geral, Testes A/B só podem ser atualizados quando o status é SCHEDULED. Há uma exceção: é possível atualizar o end_time do Teste A/B enquanto ele está LIVE. Este endpoint oferece suporte a JSON parcial com IDs de objeto. Aplicam-se os seguintes princípios:
  • Para adicionar ou remover objetos ou elementos, envie o array inteiro (e suas subestruturas); esta é uma operação de substituição
  • Caso contrário, modifique (alterar, adicionar, remover) fields existentes referenciando nomes de chave ou IDs
    • Para remover um field, defina seu valor como null
    • Fields que não são enviados não são modificados
Por exemplo, adicionar um terceiro grupo de usuários ao Teste A/B criado anteriormente exigiria enviar o array user_groups com os dois objetos de grupo de usuários existentes, bem como o novo que se deseja adicionar. Pense nisso como recriar o array user_groups; envie os data como se estivesse criando dessa forma desde o início (não envie IDs de objetos de grupos de usuários). O array user_groups na solicitação de atualização poderia ser representado da seguinte forma. 
[
  {
    "entity_ids": [
      "f2qcw",
      "f2tht"
    ],
    "size": "30.0",
    "name": "primeiro grupo"
  },
  {
    "entity_ids": [
      "f2rqi",
      "f2tws"
    ],
    "size": "30.0",
    "name": "segundo grupo",
    "description": "segundo grupo de teste A/B"
  },
  {
    "entity_ids": [
      "i1vwr",
      "i1xre"
    ],
    "size": "40.0"
  }
]
Observe que os valores de tamanho entre os objetos ainda totalizam 100,00. Se não os tivéssemos atualizado nos dois primeiros objetos — anteriormente definidos como 50,00 cada —, a solicitação teria falhado. Se, em vez disso, quiséssemos apenas adicionar uma descrição ao primeiro grupo de usuários, o array user_groups na solicitação de atualização seria representado da seguinte forma. 
[
  {
    "id": "p1bcx",
    "description": "atualizado usando uma requisição PUT"
  }
]
Fazemos referência ao objeto do grupo de usuários pelo id e incluímos apenas o campo que desejamos modificar.

​
Exemplos de solicitação

Esta seção apresenta solicitações de atualização adicionais como exemplo. Considere que elas são chamadas em sequência. Os blobs JSON estão formatados para facilitar a leitura. As respostas foram omitidas. Para fazer as modificações a seguir, a solicitação seria representada da seguinte forma. (É a mesma do exemplo usado anteriormente.)
  1. Adiciona um terceiro grupo de usuários sem nome ou descrição
  2. Altera a porcentagem de usuários em cada grupo de usuários
twurl -X PUT -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests/hr7l0” -d ’ 
twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "user_groups": [
    {
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ],
      "size": "30.00",
      "name": "primeiro grupo"
    },
    {
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ],
      "size": "30.00",
      "name": "segundo grupo",
      "description": "segundo grupo do teste AB"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "40.00"
    }
  ]
}'
Para fazer as seguintes modificações, a solicitação seria representada da seguinte forma.
  1. Remove a descrição do teste A/B
  2. Adiciona uma descrição ao primeiro grupo de usuários
  3. Adiciona um id de entidade (f2syz) ao segundo grupo de usuários
twurl -X PUT -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests/hr7l0” -d ’ 
twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "description": null,
  "user_groups": [
    {
      "id": "p1bcx",
      "description": "primeiro grupo de teste AB"
    },
    {
      "id": "p1bcy",
      "entity_ids": [
        "f2rqi",
        "f2tws",
        "f2syz"
      ]
    }
  ]
}'
A terceira modificação exige que passemos os dois IDs de entidade existentes junto com o novo. Observe que nenhuma alteração foi feita no terceiro grupo de usuários. Para realizar as seguintes modificações, a solicitação seria representada da seguinte forma.
  1. Remove o segundo grupo de usuários
  2. Altera a porcentagem de usuários em cada grupo de usuários 
twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "user_groups": [
    {
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ],
      "size": "55.00",
      "name": "primeiro grupo"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "45.00"
    }
  ]
}'

​
Referência da API

​
Testes A/B

​
GET accounts/:account_id/ab_tests

Recupere detalhes de alguns ou de todos os testes A/B.
URL do recurso
https://ads-api.x.com/12/accounts/:account_id/ab_tests
Parâmetros
NomeDescrição
account_id
obrigatório		O identificador da conta em uso. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Type: string

Example: 18ce54d4x5t
ab_test_ids
opcional		Restrinja a resposta apenas aos testes A/B desejados especificando uma lista de identificadores separados por vírgulas. Até 200 IDs podem ser fornecidos.

Type: string

Example: hr7l0
count
opcional		Especifica o número de registros a tentar recuperar por solicitação.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
opcional		Especifica um cursor para obter a próxima página de resultados. Consulte Pagination para mais informações.

Type: string

Example: 8x7v00oow
live_during
opcional		Restrinja a resposta aos testes A/B que estiveram ou estarão ativos durante o intervalo de datas fornecido. Retorna testes A/B cujos horários de início e término se sobrepõem — parcial ou totalmente — ao intervalo especificado.

Especifique valores como datas separadas por vírgulas, expressas em ISO 8601. A data mais antiga deve ser informada primeiro.

Type: string

Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z
q
opcional		Uma query opcional para filtrar o recurso por name. Omita este parâmetro para recuperar todos.

Type: string

Min, Max length: 1, 80
sort_by
opcional		Ordena pelo atributo compatível em ordem ascendente ou descendente. Consulte Sorting para mais informações.

Type: string

Example: created_at-asc
status
opcional		Restrinja a resposta aos testes A/B com o status desejado.

Type: enum

Possible values: COMPLETED, LIVE, SCHEDULED
user_id
opcional		Restrinja a resposta aos testes A/B criados pelo ID de usuário especificado.

Observação: Não pode ser especificado ao mesmo tempo que username.

Type: long

Example: 756201191646691328
username
opcional		Restrinja a resposta aos testes A/B criados pelo nome de usuário especificado. Não inclua o símbolo ”@”.

Observação: Não pode ser especificado ao mesmo tempo que user_id.

Type: string

Example: apimctestface
with_deleted
opcional		Incluir resultados excluídos na sua solicitação.

Type: boolean

Default: false
Possible values: true, false
Exemplo de requisição
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests
Exemplo de resposta
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        {
          "created_at": "2022-05-25T00:00:00Z",
          "created_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          },
          "deleted": false,
          "description": "exemplo de documentação",
          "end_time": "2022-05-30T01:00:00Z",
          "entities": [
            {
              "id": "p1bcx",
              "account_id": "18ce54d4x5t"
            },
            {
              "id": "p1bcy",
              "account_id": "18ce54d4x5t"
            }
          ],
          "entity_type": "CAMPAIGN",
          "id": "hr7l0",
          "name": "primeiro teste AB",
          "start_time": "2022-05-25T01:00:00Z",
          "status": "SCHEDULED",
          "user_groups": [
            {
              "id": "p1bcx",
              "name": "primeiro grupo",
              "description": null,
              "size": "50.0",
              "entity_ids": [
                "f2qcw",
                "f2tht"
              ]
            },
            {
              "id": "p1bcy",
              "name": "segundo grupo",
              "description": "segundo grupo de teste AB",
              "size": "50.0",
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ]
            }
          ],
          "updated_at": "2022-05-25T00:00:00Z",
          "updated_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          }
        }
      ],
      "next_cursor": null
    }

​
POST accounts/:account_id/ab_tests

Crie um novo teste A/B. Todos os parâmetros são enviados no corpo da requisição, e é necessário definir o Content-Type como application/json.
URL do recurso
https://ads-api.x.com/12/accounts/:account_id/ab_tests
Parâmetros
NomeDescrição
account_id
obrigatório		O identificador da conta aproveitada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, exceto GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Type: string

Example: 18ce54d4x5t
end_time
obrigatório		O horário, em formato ISO 8601, em que o teste A/B terminará.

Type: string

Example: 2020-10-02T00:00:00Z
entity_type
obrigatório		O tipo de entidade a ser usado para divisão dos grupos de usuários.

Type: enum

Possible values: CAMPAIGN, LINE_ITEM
start_time
obrigatório		O horário, em formato ISO 8601, em que o teste A/B começará.

Type: string

Example: 2022-05-30T00:00:00Z
user_groups
obrigatório		Descreve os grupos de usuários. Mais informações na tabela abaixo. Podem ser especificados entre 2 e 30 grupos de usuários.

Type: array of objects
description
opcional		A descrição do teste A/B. Comprimento máximo: 1.024 caracteres.

Type: string

Example: documentation example
name
opcional		O nome do teste A/B. Comprimento máximo: 255 caracteres.

Type: string

Example: first AB test

​
Grupos de usuários

NomeDescrição
entity_ids
obrigatório		Um array de IDs de entidade.

Observação: As entidades só podem ser associadas a um único teste A/B.

Type: array

Example: ["dxi0l", "e66bl"]
size
obrigatório		A porcentagem de usuários a ser alocada para este grupo de usuários. Este é um valor numérico representado como uma string com no máximo duas casas decimais. Por exemplo, represente 40% como: 40, 40.0 ou 40.00.

Observação: Os valores de size entre objects devem somar 100.00.

Type: array

Min, Max: 1.00, 99.00
description
opcional		A descrição do grupo de usuários. Comprimento máximo: 1.024 caracteres.

Type: string

Example: second AB test group
name
opcional		O nome do grupo de usuários. Comprimento máximo: 255 caracteres.

Type: string

Example: first group

​
Exemplo de requisição

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests -d '{"end_time": "2022-05-30T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2022-05-25T01:00:00Z", "user_groups": [{"entity_ids": ["f2qcw", "f2tht"], "size": "50.00", "name": "first group"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "second group", "description": "second AB test group"}], "name": "first AB test", "description": "documentation example"}'

​
Exemplo de resposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "end_time": "2022-05-30T01:00:00Z",
          "entity_type": "CAMPAIGN",
          "start_time": "2022-05-25T01:00:00Z",
          "user_groups": [
            {
              "entity_ids": [
                "f2qcw",
                "f2tht"
              ],
              "size": "50.0",
              "name": "primeiro grupo"
            },
            {
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ],
              "size": "50.0",
              "name": "second group",
              "description": "segundo grupo de teste A/B"
            }
          ],
          "name": "primeiro teste A/B"
          "description": "exemplo da documentação"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": "exemplo da documentação",
        "end_time": "2022-05-30T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "primeiro teste A/B",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "primeiro grupo",
            "description": null,
            "size": "50.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "segundo grupo",
            "description": "segundo grupo de teste A/B",
            "size": "50.0",
            "entity_ids": [
              "f2rqi",
              "f2tws"
            ]
          }
        ],
        "updated_at": "2022-05-25T00:00:00Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }

​
PUT accounts/:account_id/ab_tests/:ab_test_id

Atualize o teste A/B especificado. Todos os parâmetros são enviados no corpo da solicitação e é necessário definir o Content-Type como application/json. Este endpoint oferece suporte a JSON parcial com IDs de objeto. Aplicam-se os seguintes princípios:
  • Para adicionar ou remover objetos ou elementos, envie o array inteiro (e suas subestruturas); esta é uma operação de substituição
    • Pense nisso como recriar o array
  • Caso contrário, modifique (alterando, adicionando ou removendo) os campos existentes referenciando nomes de chave ou IDs
    • Para remover um campo, defina seu valor como null
    • Campos que não forem enviados não serão modificados
Em geral, testes A/B só podem ser atualizados enquanto o status estiver como SCHEDULED. Há uma exceção: é possível atualizar o end_time do teste A/B enquanto ele estiver LIVE.
URL do recurso
https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id
Parâmetros
NomeDescrição
account_id
obrigatório		O identificador da conta alavancada. Aparece no caminho do recurso e geralmente é um parâmetro obrigatório para todas as solicitações da Advertiser API, com exceção de GET accounts. A conta especificada deve estar associada ao usuário autenticado.

Type: string

Example: 18ce54d4x5t
ab_test_id
obrigatório		Uma referência ao teste A/B com o qual você está operando na solicitação.

Type: string

Example: hr7l0
description
opcional		A descrição do teste A/B. Comprimento máximo: 1.024 caracteres.

Observação: Só pode ser atualizada enquanto o status do teste A/B for SCHEDULED.

Type: string

Example: documentation example
end_time
opcional		O horário, em formato ISO 8601, em que o teste A/B terminará.

Observação: Só pode ser atualizada enquanto o status do teste A/B for SCHEDULED ou LIVE.

Type: string

Example: 2020-10-02T00:00:00Z
name
opcional		O nome do teste A/B. Comprimento máximo: 255 caracteres.

Observação: Só pode ser atualizada enquanto o status do teste A/B for SCHEDULED.

Type: string

Example: first AB test
start_time
opcional		O horário, em formato ISO 8601, em que o teste A/B começará.

Observação: Só pode ser atualizada enquanto o status do teste A/B for SCHEDULED.

Type: string

Example: 2022-05-30T00:00:00Z
user_groups
obrigatório		Descreve os grupos de usuários. Mais informações na tabela abaixo.

Observação: Só pode ser atualizada enquanto o status do teste A/B for SCHEDULED.

Type: array of objects

​
Grupos de usuários

NomeDescrição
id
às vezes obrigatório		Uma referência ao objeto de grupo de usuários com o qual você está operando na solicitação.

Observação: Obrigatório ao modificar (alterar, adicionar ou remover) fields do objeto de grupo de usuários.

Observação: Não especifique um id ao adicionar ou remover objetos de grupo de usuários inteiros.

Type: string

Example: p1bcx
description
opcional		A descrição do grupo de usuários. Tamanho máximo: 1.024 caracteres.

Observação: Remova definindo o campo com o valor null.

Type: string

Example: second AB test group
entity_ids
opcional		Um array de IDs de entidades.

Observação: Esta é uma operação de substituição. Ela sobrescreve o que foi definido anteriormente.

Observação: As entidades só podem ser associadas a um teste A/B.

Type: array

Example: ["dxi0l", "e66bl"]
name
opcional		O nome do grupo de usuários. Tamanho máximo: 255 caracteres.

Observação: Remova definindo o campo com o valor null.

Type: string

Example: first group
size
opcional		A porcentagem de usuários a alocar para este grupo de usuários. Este é um valor numérico representado como string com no máximo duas casas decimais. Por exemplo, represente 40% como: 40, 40.0 ou 40.00.

Observação: Os valores de tamanho entre os objects devem somar 100.00.

Type: string

Min, Max: 1.00, 99.00
Exemplo de solicitação
Esta solicitação faz as seguintes modificações:
  1. Remove a descrição do teste A/B
  2. Altera o horário de término
  3. Adiciona uma descrição ao primeiro grupo de usuários
  4. Altera a porcentagem de usuários em cada grupo de usuários
  5. Adiciona um ID de entidade (f2syz) ao segundo grupo de usuários
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0 -d '{"description": null, "end_time": "2022-06-01T01:00:00Z", "user_groups": [{"id": "p1bcx", "description": "first AB test group", "size": "60.00"},{"id": "p1bcy", "size": "40.00", "entity_ids": ["f2rqi", "f2tws", "f2syz"]}]}'
Exemplo de resposta
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0",
          "description": null,
          "end_time": "2022-06-01T01:00:00Z",
          "user_groups": [
            {
              "id": "p1bcx",
              "description": "primeiro grupo do teste A/B",
              "size": "60.0"
            },
            {
              "id": "p1bcy",
              "size": "40.0",
              "entity_ids": [
                "f2rqi",
                "f2tws",
                "f2syz"
              ]
            }
          ]
        }
      },
      "data": {
        "created_at": "2020-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": null,
        "end_time": "2022-06-01T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "primeiro teste A/B",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "primeiro grupo",
            "description": "primeiro grupo do teste A/B",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "segundo grupo",
            "description": "segundo grupo do teste A/B"
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-05-25T00:17:23Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }

​
DELETE accounts/:account_id/ab_tests/:ab_test_id

Exclui o A/B Test especificado. Observação: A exclusão de um A/B Test é irreversível e tentativas subsequentes de excluí-lo retornarão HTTP 404.
URL do recurso
https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id
Parâmetros
NomeDescrição
ab_test_id
obrigatório		Referência ao teste A/B utilizado na solicitação.

Type: string

Example: hr7l0
Exemplo de requisição
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0

​
Exemplo de resposta

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": true,
        "description": null,
        "end_time": "2022-06-01T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "primeiro teste A/B",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "primeiro grupo",
            "description": "primeiro grupo de teste A/B",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "segundo grupo",
            "description": "segundo grupo de teste A/B"
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-06-02T00:18:31Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }
⌘I