AdControl in HTML 5 e JavaScriptAdControl in HTML 5 and JavaScript

Avviso

A partire dal 1 ° giugno 2020, la piattaforma di monetizzazione di Microsoft ad per le app UWP di Windows verrà arrestata.As of June 1, 2020, the Microsoft Ad Monetization platform for Windows UWP apps will be shut down. Scopri di piùLearn more

Questa procedura dettagliata illustra come usare la classe AdControl per visualizzare gli annunci banner in un'app JavaScript/HTML piattaforma UWP (Universal Windows Platform) (UWP) per Windows 10.This walkthrough shows how to use the AdControl class to display banner ads in a Universal Windows Platform (UWP) JavaScript/HTML app for Windows 10.

Per un progetto di esempio completo che mostra come aggiungere annunci banner a un'app JavaScript/HTML, vedi Esempi di annunci su GitHub.For a complete sample project that demonstrates how to add banner ads to a JavaScript/HTML app, see the advertising samples on GitHub.

PrerequisitiPrerequisites

Nota

Se è stata installata la versione di Windows 10 SDK 10.0.14393 (aggiornamento dell'anniversario) o una versione successiva del Windows SDK, è necessario installare anche la libreria WinJS .If you have installed the Windows 10 SDK version 10.0.14393 (Anniversary Update) or a later version of the Windows SDK, you must also install the WinJS library. Questa libreria era inclusa nelle versioni precedenti del Windows SDK per Windows 10, ma a partire da Windows 10 SDK versione 10.0.14393 (aggiornamento dell'anniversario) questa libreria deve essere installata separatamente.This library used to be included in previous versions of the Windows SDK for Windows 10, but starting with the Windows 10 SDK version 10.0.14393 (Anniversary Update) this library must be installed separately.

Integrare un annuncio banner nell'appIntegrate a banner ad into your app

  1. In Visual Studio apri il tuo progetto o creane uno nuovo.In Visual Studio, open your project or create a new project.

    Nota

    Se si usa un progetto esistente, aprire il file Package. appxmanifest nel progetto e verificare che sia selezionata la funzionalità Internet (client) .If you're using an existing project, open the Package.appxmanifest file in your project and ensure that the Internet (Client) capability is selected. L'app necessita di questa funzionalità per ricevere annunci di test e annunci Live.Your app needs this capability to receive test ads and live ads.

  2. Se il progetto specifica come destinazione Qualsiasi CPU, aggiornalo per poter usare un output di compilazione specifico dell'architettura (ad esempio, x86).If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). Se il progetto specifica come destinazione Qualsiasi CPU, non riuscirai ad aggiungere un riferimento alla libreria Microsoft Advertising nei passaggi seguenti.If your project targets Any CPU, you will not be able to successfully add a reference to the Microsoft advertising library in the following steps. Per altre informazioni, vedi Errori di riferimento generati specificando come destinazione Qualsiasi CPU in nel progetto.For more information, see Reference errors caused by targeting Any CPU in your project.

  3. Aggiungere un riferimento a Microsoft Advertising SDK nel progetto:Add a reference to the Microsoft Advertising SDK in your project:

    1. Nella finestra Esplora soluzioni fai clic con il pulsante destro del mouse su Riferimenti e quindi scegli Aggiungi riferimento.From the Solution Explorer window, right click References, and select Add Reference…
    2. In Gestione riferimenti espandi Windows universale, fai clic su Estensioni e quindi seleziona la casella di controllo accanto a Microsoft Advertising SDK for JavaScript (versione 10.0).In Reference Manager, expand Universal Windows, click Extensions, and then select the check box next to Microsoft Advertising SDK for JavaScript (Version 10.0).
    3. In Gestione riferimenti fai clic su OK.In Reference Manager, click OK.
  4. Apri il file index.html (o un altro file HTML appropriato per il tuo progetto).Open the index.html file (or other html file as appropriate for your project).

  5. Nella sezione ** < Head > ** , dopo i riferimenti JavaScript del progetto di default. CSS e main.js, aggiungere il riferimento a ad.js.In the <head> section, after the project’s JavaScript references of default.css and main.js, add the reference to ad.js.

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

    Nota

    Questa riga deve essere inserita nella sezione ** < Head > ** dopo l'inclusione di main.js; in caso contrario, si verificherà un errore quando si compila il progetto.This line must be placed in the <head> section after the include of main.js; otherwise, you will encounter an error when you build your project.

  6. Modificare la sezione ** < Body > ** nel file default.html (o in un altro file HTML nel modo appropriato per il progetto) per includere il div per AdControl.Modify the <body> section in the default.html file (or other html file as appropriate for your project) to include the div for the AdControl. Assegnare le proprietà ApplicationID e adUnitId di AdControl ai valori dell' unità ad di test.Assign the applicationId and adUnitId properties of the AdControl to the test ad unit values. Modificare anche l' altezza e la larghezza in modo che il controllo sia una delle dimensioni ad supportate per gli annunci banner.Also adjust the height and width so the control is one of the supported ad sizes for banner ads.

    Nota

    Ogni AdControl dispone di un' unità ad corrispondente usata dai servizi per fornire annunci al controllo e ogni unità ad è costituita da un ID di unità di annuncio e da un ID applicazione.Every AdControl has a corresponding ad unit that is used by our services to serve ads to the control, and every ad unit consists of an ad unit ID and application ID. In questi passaggi si assegnano i valori di ID unità e ID applicazione del test al controllo.In these steps, you assign test ad unit ID and application ID values to your control. Questi valori di test possono essere usati solo in una versione di prova dell'app.These test values can only be used in a test version of your app. Prima di pubblicare l'app nello Store, è necessario sostituire questi valori di test con valori Live dal centro per i partner.Before you publish your app to the Store, you must replace these test values with live values from 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. Compila ed esegui l'app per vederla con un annuncio.Compile and run the app to see it with an ad.

Nell'esempio seguente viene illustrato l'intero index.html per un'app semplice.The following example shows the complete index.html for a simple app.

<!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>

Creare un AdControl a livello di codice in JavaScriptCreate an AdControl programmatically in Javascript

Nei passaggi precedenti viene illustrato come dichiarare un AdControl nel markup HTML.The previous steps show how to declare an AdControl in your HTML markup. In alternativa, è possibile creare un AdControl a livello di codice utilizzando JavaScript.Alternatively, you can programmatically create an AdControl using JavaScript. Questo esempio presuppone che si usi un div esistente nel codice HTML con l'ID myAd.This example assumes that you are using an existing div in your HTML with the 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;

Questo esempio assume che hai già dichiarato i metodi di gestore eventi denominati myAdError, myAdRefreshed e myAdEngagedChanged.This example assumes that you have already declared event handler methods named myAdError, myAdRefreshed, and myAdEngagedChanged.

Se usi questo codice e non vedi gli annunci, puoi provare a inserire un attributo di position:relative nell'elemento div che contiene AdControl.If you use this code and do not see ads, you can try inserting an attribute of position:relative in the div that contains the AdControl. Questo eseguirà l'override dell'impostazione predefinita di IFrame.This will override the default setting of the IFrame. Gli annunci verranno visualizzati correttamente, tranne nel caso in cui non sono visibili a causa del valore di questo attributo.Ads will be displayed correctly, unless they are not being shown due to the value of this attribute. Tieni presente che le nuove unità pubblicitarie potrebbero non essere disponibili per un massimo di 30 minuti.Note that new ad units may not be available for up to 30 minutes.

Nota

I valori ApplicationID e adUnitId indicati in questo esempio sono valori della modalità di test.The applicationId and adUnitId values shown in this example are test mode values. È necessario sostituire questi valori con i valori Live del centro per i partner prima di inviare l'app per l'invio.You must replace these values with live values from Partner Center before submitting your app for submission.

Rilascia l'app con annunci LiveRelease your app with live ads

  1. Assicurarsi che l'uso di banner ads nell'app segua le linee guida per gli annunci banner.Make sure your use of banner ads in your app follows our guidelines for banner ads.

  2. Nel centro per i partner passare alla pagina ads in-app e creare un'unità ad.In Partner Center, go to the In-app ads page and create an ad unit. Come tipo di unità pubblicitaria, specifica Banner.For the ad unit type, specify Banner. Prendi nota sia dell'ID unità pubblicitaria che dell'ID applicazione.Make note of both the ad unit ID and the application ID.

    Nota

    I valori dell'ID applicazione per le unità di ad di test e le unità ad UWP attive hanno formati diversi.The application ID values for test ad units and live UWP ad units have different formats. I valori ID dell'applicazione di test sono GUID.Test application ID values are GUIDs. Quando si crea un'unità ad UWP in tempo reale nel centro per i partner, il valore dell'ID applicazione per l'unità ad corrisponde sempre all'ID dello Store per l'app (un esempio di valore ID archivio è simile a 9NBLGGH4R315).When you create a live UWP ad unit in Partner Center, the application ID value for the ad unit always matches the Store ID for your app (an example Store ID value looks like 9NBLGGH4R315).

  3. Facoltativamente, è possibile abilitare la mediazione di ad per il AdControl configurando le impostazioni nella sezione Impostazioni Mediation della pagina ads in-app .You can optionally enable ad mediation for the AdControl by configuring the settings in the Mediation settings section on the In-app ads page. La mediazione di ad consente di massimizzare le funzionalità per la promozione delle app e dei ricavi di Active Directory visualizzando annunci da più reti ad, inclusi gli annunci di altre reti ad a pagamento, ad esempio taboola e Smaato e ADS per le campagne di promozione delle app Microsoft.Ad mediation enables you to maximize your ad revenue and app promotion capabilities by displaying ads from multiple ad networks, including ads from other paid ad networks such as Taboola and Smaato and ads for Microsoft app promotion campaigns.

  4. Nel codice sostituire i valori di unità ad di test (ApplicationID e adUnitId) con i valori Live generati nel centro per i partner.In your code, replace the test ad unit values (applicationId and adUnitId) with the live values you generated in Partner Center.

  5. Invia l'app allo Store usando il centro per i partner.Submit your app to the Store using Partner Center.

  6. Esaminare i report di prestazioni pubblicitari nel centro per i partner.Review your advertising performance reports in Partner Center.

Gestire le unità ad per più controlli ad nell'appManage ad units for multiple ad controls in your app

È possibile usare più oggetti AdControl in una singola app. ad esempio, ogni pagina dell'app potrebbe ospitare un oggetto AdControl diverso.You can use multiple AdControl objects in a single app (for example, each page in your app might host a different AdControl object). In questo scenario si consiglia di assegnare un'unità ad diversa a ogni controllo.In this scenario, we recommend that you assign a different ad unit to each control. L'uso di diverse unità ad per ogni controllo consente di configurare separatamente le impostazioni di mediazione e ottenere dati di report discreti per ogni controllo.Using different ad units for each control enables you to separately configure the mediation settings and get discrete reporting data for each control. In questo modo i nostri servizi consentono di ottimizzare meglio gli annunci usati per la tua app.This also enables our services to better optimize the ads we serve to your app.

Importante

È possibile usare ogni unità ad in una sola app.You can use each ad unit in only one app. Se si usa un'unità pubblicitaria in più app, gli annunci non verranno serviti per l'unità ad.If you use an ad unit in more than one app, ads will not be served for that ad unit.