Compartilhar via

Gerenciar campanhas publicitárias

  • Artigo

Use esses métodos na API de promoções da Microsoft Store para criar, editar e obter campanhas publicitárias promocionais para seu aplicativo. Cada campanha criada usando esse método pode ser associada a apenas um aplicativo.

Observação Você também pode criar e gerenciar campanhas publicitárias usando o Partner Center, e as campanhas criadas programaticamente podem ser acessadas no Partner Center. Para obter mais informações sobre como gerenciar campanhas publicitárias no Partner Center, consulte Criar uma campanha publicitária para seu aplicativo.

Ao usar esses métodos para criar ou atualizar uma campanha, você normalmente também chama um ou mais dos seguintes métodos para gerenciar as linhas de exibição, os perfis de segmentação e os criativos associados à campanha. Para obter mais informações sobre a relação entre campanhas, linhas de exibição, perfis de segmentação e criativos, consulte Executar campanhas publicitárias usando os serviços da Microsoft Store.

Pré-requisitos

Para usar esses métodos, primeiro você precisa fazer o seguinte:

  • Se você ainda não fez isso, conclua todos os pré-requisitos para a API de promoções da Microsoft Store.

    Observação Como parte dos pré-requisitos, certifique-se de criar pelo menos uma campanha publicitária paga no Partner Center e de adicionar pelo menos um instrumento de pagamento para a campanha publicitária no Partner Center. As linhas de entrega para campanhas publicitárias criadas usando essa API cobrarão automaticamente o instrumento de pagamento padrão escolhido na página Campanhas publicitárias no Partner Center.

  • Obtenha um token de acesso do Azure AD para usar no cabeçalho de solicitação para esses métodos. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá obter um novo.

Solicitação

Esses métodos têm as URIs a seguir.

Tipo de método URI da solicitação Descrição
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Cria uma nova campanha publicitária.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Edita a campanha publicitária especificada por campaignId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Obtém a campanha publicitária especificada por campaignId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Consultas para campanhas publicitárias. Consulte a seção Parâmetros para obter os parâmetros de consulta com suporte.
parâmetro Tipo Descrição
Autorização string Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário.
ID de rastreamento GUID Opcional. Uma ID que rastreia o fluxo de chamadas.

 

Parâmetros

O método GET para consultar campanhas publicitárias é compatível com os seguintes parâmetros de consulta opcionais.

Nome Tipo Descrição
skip int O número de linhas a serem ignoradas na consulta. Use esse parâmetro para percorrer os conjuntos de dados. Por exemplo, fetch=10 e skip=0 recuperam as primeiras 10 linhas de dados, top=10 e skip=10 recuperam as próximas 10 linhas de dados e assim por diante.
fetch int O número de linhas de dados a serem retornadas na solicitação.
campaignSetSortColumn string Ordena os objetos do Campaign no corpo da resposta pelo campo especificado. A sintaxe é CampaignSetSortColumn=field, em que o parâmetro field pode ser uma das seguintes strings:

  • id
  • createdDateTime

O padrão é createdDateTime.
é descendente Booliano Classifica os objetos Campaign no corpo da resposta em ordem decrescente ou crescente.
storeProductId string Use esse valor para retornar apenas as campanhas publicitárias associadas ao aplicativo com o ID da loja especificado. Um exemplo de ID da loja para um produto é 9nblggh42cfd.
label string Use esse valor para retornar apenas as campanhas publicitárias que incluem o rótulo especificado no objeto Campaign.

Corpo da solicitação

Os métodos POST e PUT exigem um corpo de solicitação JSON com os campos obrigatórios de um objeto do Campaign e quaisquer campos adicionais que você deseja definir ou alterar.

Exemplos de solicitação

O exemplo a seguir demonstra como chamar o método POST para criar uma campanha publicitária.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign",
    "storeProductId": "9nblggh42cfd",
    "configuredStatus": "Active",
    "objective": "DriveInstalls",
    "type": "Community"
}

O exemplo a seguir demonstra como chamar o método GET para recuperar uma campanha publicitária específica.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/31043481  HTTP/1.1
Authorization: Bearer <your access token>

O exemplo a seguir demonstra como chamar o método GET para consultar um conjunto de campanhas publicitárias, classificadas pela data de criação.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?storeProductId=9nblggh42cfd&fetch=100&skip=0&campaignSetSortColumn=createdDateTime HTTP/1.1
Authorization: Bearer <your access token>

Resposta

Esses métodos retornam um corpo de resposta JSON com um ou mais objetos do Campaign , dependendo do método chamado. O exemplo a seguir demonstra um corpo de resposta para o método GET para uma campanha específica.

{
    "Data": {
        "id": 31043481,
        "name": "Contoso App Campaign",
        "createdDate": "2017-01-17T10:12:15Z",
        "storeProductId": "9nblggh42cfd",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "labels": [],
        "objective": "DriveInstalls",
        "type": "Paid",
        "lines": [
            {
                "id": 31043476,
                "name": "Contoso App Campaign - Paid Line"
            }
        ]
    }
}

Objeto de campanha

Os corpos de solicitação e resposta para esses métodos contêm os campos a seguir. Esta tabela mostra quais campos são somente leitura (o que significa que eles não podem ser alterados no método PUT) e quais campos são necessários no corpo da solicitação para o método POST.

Campo Type Description Somente leitura Padrão Necessário para POST
id Número inteiro A ID da campanha publicitária. Sim Não
name string O nome da campanha publicitária. Não Sim
Status configurado string Um dos seguintes valores que especifica o status da campanha publicitária especificada pelo desenvolvedor:
  • Com atividade
  • Inativo
 Não Ativo Sim
status efetivo string Um dos seguintes valores que especifica o status efetivo da campanha publicitária com base na validação do sistema:
  • Com atividade
  • Inativo
  • Em processamento
 Sim No
effectiveStatusReasons matriz Um ou mais dos seguintes valores que especificam o motivo do status efetivo da campanha publicitária:
  • AnúnciosCriativosInativo
  • Falha no faturamento
  • AdLinesInativo
  • Falha na validação
  • Com falha
 Sim No
storeProductId string O ID da loja do aplicativo ao qual essa campanha publicitária está associada. Um exemplo de ID da loja para um produto é 9nblggh42cfd. Sim Sim
rótulos matriz Uma ou mais strings que representam rótulos personalizados para a campanha. Esses rótulos podem ser usados para pesquisar e marcar campanhas. Não nulo Não
type string Um dos seguintes valores que especifica o tipo de campanha:
  • Pago
  • Casa
  • Comunidade
 Sim Sim
objetivo string Um dos seguintes valores que especifica o objetivo da campanha:
  • UnidadeInstalar
  • DriveReengagement
  • DriveInAppPurchase
 Não UnidadeInstalar Sim
lines matriz Um ou mais objetos que identificam as linhas de entrega associadas à campanha publicitária. Cada objeto nesse campo consiste em um campo id e name que especifica o ID e o nome da linha de entrega. Não No
createdDate string A data e a hora em que a campanha publicitária foi criada, no formato ISO 8601. Sim No