AdControl em HTML 5 e JavaScript

  • Artigo

Aviso

A partir de 1º de junho de 2020, a plataforma Microsoft Ad Monetization para aplicativos UWP do Windows será desligada. Saiba mais

Este passo a passo mostra como usar a classe AdControl para exibir anúncios em faixa em um aplicativo JavaScript/HTML de Plataforma Universal do Windows (UWP) para Windows 10 e Windows 11.

Para um projeto de exemplo completo que demonstra como adicionar anúncios em um aplicativo JavaScript/HTML, consulte os exemplos de publicidade no GitHub.

Pré-requisitos

Observação

Se você instalou o SDK do Windows 10 versão 10.0.14393 (Atualização de Aniversário) ou uma versão posterior do SDK do Windows, também deverá instalar a biblioteca do WinJS. Essa biblioteca costumava ser incluída em versões anteriores do SDK do Windows para Windows 10, mas a partir da versão 10.0.14393 do SDK do Windows 10 (Atualização de Aniversário), ela deve ser instalada separadamente.

Integrar um anúncio em faixa ao seu aplicativo

  1. No Visual Studio, abra o projeto ou crie um novo projeto.

    Observação

    Se você estiver usando um projeto existente, abra o arquivo Package. appxmanifest em seu projeto e certifique-se de que o recurso da Internet (cliente) está selecionado. Seu aplicativo precisa dessa funcionalidade para receber anúncios de teste e anúncios ativos.

  2. Se o seu projeto tem direcionamento Any CPU, atualize-o para usar uma saída de compilação de arquitetura específica (por exemplo, x86). Se o seu projeto tem direcionamento Any CPU, você não conseguirá adicionar uma referência à biblioteca do Microsoft Advertising nas etapas a seguir. Para obter mais informações, consulte Erros de referência causados pelo direcionamento Any CPU em seu projeto.

  3. Adicione uma referência ao SDK do Microsoft Advertising em seu projeto:

    1. Na janela Gerenciador de Soluções, clique com o botão direito do mouse em Referências e selecione Adicionar Referência...
    2. No Gerenciador de Referências, expanda Universal do Windows, clique em Extensões e marque a caixa de seleção ao lado de SDK do Microsoft Advertising para JavaScript (versão 10.0).
    3. No Gerenciador de Referências, clique em OK.

  4. Abra o arquivo index.html (ou outro arquivo html apropriado para o seu projeto).

  5. <Na seção principal>, após as referências javaScript do projeto de default.css e main.js, adicione a referência a ad.js.

    <!-- Advertising required references -->
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>

    Observação

    Essa linha deve ser colocada na <seção principal> após a inclusão de main.js; caso contrário, você encontrará um erro ao compilar seu projeto.

  6. Modifique a <seção body> no arquivo default.html (ou outro arquivo html conforme apropriado para o projeto) para incluir o div para o AdControl. Atribua as propriedades applicationId e adUnitId no AdControl aos valores de teste fornecidos em valores de unidade publicitária de teste. Ajuste também a altura e a largura do controle para que ele tenha um dos tamanhos de anúncio compatíveis para anúncios em faixa.

    Observação

    Cada AdControl tem uma unidade publicitária correspondente que é usado por nossos serviços para veicular anúncios para o controle, e cada unidade publicitária consiste em uma ID da unidade publicitária e ID do aplicativo. Nestas etapas, você atribui os valores da ID da unidade publicitária de teste e da ID do aplicativo para seu controle. Esses valores de teste só podem ser usados em uma versão de teste do seu app. Antes de publicar seu aplicativo na Store, você deve substituir esses valores de teste por valores dinâmicos do Partner Center.

    <div id="myAd" style="position: absolute; top: 50px; left: 0px; width: 300px; height: 250px; z-index: 1"
    data-win-control="MicrosoftNSJS.Advertising.AdControl"
    data-win-options="{applicationId: '3f83fe91-d6be-434d-a0ae-7351c5a997f1', adUnitId: 'test'}">
</div>

  7. Compile e execute o aplicativo para vê-lo com um anúncio.

O exemplo a seguir mostra o index.html completo para um aplicativo simples.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>AdControlExampleApp</title>
    <!-- WinJS references -->
    <link href="lib/winjs-4.0.1/css/ui-light.css" rel="stylesheet" />
    <script src="lib/winjs-4.0.1/js/base.js"></script>
    <script src="lib/winjs-4.0.1/js/ui.js"></script>
    <!-- AdControlExampleApp references -->
    <link href="css/default.css" rel="stylesheet" />
    <script src="js/main.js"></script>
    <!-- Required reference for AdControl -->
    <script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
</head>
<body>
    <div id="myAd" style="position: absolute; top: 50px; left: 0px; width: 300px; height: 250px; z-index: 1"
      data-win-control="MicrosoftNSJS.Advertising.AdControl"
      data-win-options="{applicationId: '3f83fe91-d6be-434d-a0ae-7351c5a997f1', adUnitId: 'test'}">
    </div>
    <p>Content goes here</p>
</body>
</html>

Criar um AdControl programaticamente no JavaScript

As etapas anteriores mostram como declarar um AdControl na marcação HTML. Como alternativa, você pode criar programaticamente um AdControl usando JavaScript. Este exemplo considera que você esteja usando um div existente em seu HTML com a ID myAd.

var adDiv = document.getElementById("myAd");
var myAdControl = new MicrosoftNSJS.Advertising.AdControl(adDiv,
{
    applicationId: "3f83fe91-d6be-434d-a0ae-7351c5a997f1",
    adUnitId: "test",
});

myAdControl.isAutoRefreshEnabled = false;
myAdControl.onErrorOccurred = myAdError;
myAdControl.onAdRefreshed = myAdRefreshed;
myAdControl.onEngagedChanged = myAdEngagedChanged;

Este exemplo presume que você já tenha declarado os métodos de manipulador de eventos chamados myAdError, myAdRefreshed e myAdEngagedChanged.

Se você usa esse código e não vê anúncios, tente inserir um atributo position:relative no div que contém o AdControl. Isso substituirá a configuração padrão do IFrame. Os anúncios serão exibidos corretamente, a menos que eles não estejam sendo mostrados devido ao valor desse atributo. Observe que novas unidades de anúncios podem não estar disponíveis por até 30 minutos.

Observação

Os valores de applicationId e adUnitId mostrados neste exemplo são valores de modo de teste. Você deve substituir esses valores por valores dinâmicos do Partner Center antes de enviar seu aplicativo para envio.

Liberar seu app com anúncios ativos

  1. Verifique se o uso de anúncios em faixa no aplicativo segue as diretrizes para anúncios em faixa.

  2. No Partner Center, acesse a página Anúncios no aplicativo e crie uma unidade de anúncios. No tipo de unidade publicitária, especifique Faixa. Anote a ID da unidade publicitária e a ID do aplicativo.

    Observação

    Os valores da ID de aplicativo para unidades publicitárias de teste e unidades publicitárias dinâmicas UWP têm formatos diferentes. Valores de ID de aplicativo de teste são GUIDs. Quando você cria uma unidade de anúncios UWP ativa no Partner Center, o valor da ID do aplicativo para a unidade de anúncios sempre corresponde à ID da Loja para seu aplicativo (um valor de ID da Loja de exemplo se parece com 9NBLGGH4R315).

  3. Como alternativa, você pode habilitar o controle de anúncios para AdControl ao definir as configurações na seção Configurações de controle na página Anúncios no app. O controle de anúncios permite que você maximize seus recursos de promoção de aplicativos e receita de anúncios exibindo anúncios de várias redes de anúncios, incluindo os anúncios de outras redes de anúncios pagas, como Taboola e Smaato e anúncios para campanhas promocionais de aplicativos da Microsoft.

  4. No código, substitua os valores de unidade de anúncio de teste (applicationId e adUnitId) pelos valores dinâmicos gerados no Partner Center.

  5. Envie seu aplicativo para a Loja usando o Partner Center.

  6. Examine seus relatórios de desempenho de publicidade no Partner Center.

Gerenciar unidades publicitárias para vários controles de anúncios em seu app

Você pode usar vários objetos AdControl em um único app (por exemplo, cada página em seu app pode hospedar um objeto AdControl diferente). Nesse cenário, nós recomendamos que você atribua uma unidade publicitária diferente para cada controle. O uso de unidades publicitárias diferentes para cada controle permite que você defina as configurações de mediação separadamente e obtenha dados de relatório discretos para cada controle. Isso também permite que nossos serviços melhorem a otimização dos anúncios veiculados em seu app.

Importante

Você pode usar cada unidade publicitária em apenas um app. Se você usar uma unidade publicitária em mais de um app, os anúncios não serão veiculados para essa unidade publicitária.