AdControl dalam HTML 5 dan JavaScript

  • Artikel

Peringatan

Mulai 1 Juni 2020, platform Monetisasi Microsoft Ad untuk aplikasi Windows UWP akan dimatikan. Pelajari lebih lanjut

Panduan ini menunjukkan cara menggunakan kelas AdControl untuk menampilkan iklan banner di aplikasi JavaScript/HTML Platform Windows Universal (UWP) untuk Windows 10 dan Windows 11.

Untuk proyek sampel lengkap yang menunjukkan cara menambahkan iklan banner ke aplikasi JavaScript/HTML, lihat sampel iklan di GitHub.

Prasyarat

Catatan

Jika Anda telah menginstal SDK Windows 10 versi 10.0.14393 (Pembaruan Hari Jadi) atau versi SDK Windows yang lebih baru, Anda juga harus menginstal pustaka WinJS. Pustaka ini digunakan untuk disertakan dalam versi Windows SDK sebelumnya untuk Windows 10, tetapi dimulai dengan SDK Windows 10 versi 10.0.14393 (Pembaruan Ulang Tahun) pustaka ini harus diinstal secara terpisah.

Mengintegrasikan iklan banner ke dalam aplikasi Anda

  1. Di Visual Studio, buka proyek Anda atau buat proyek baru.

    Catatan

    Jika Anda menggunakan proyek yang sudah ada, buka file Package.appxmanifest di proyek Anda dan pastikan bahwa kemampuan Internet (Klien) dipilih. Aplikasi Anda memerlukan kemampuan ini untuk menerima iklan pengujian dan iklan langsung.

  2. Jika proyek Anda menargetkan CPU apa pun, perbarui proyek Anda untuk menggunakan output build khusus arsitektur (misalnya, x86). Jika proyek Anda menargetkan CPU apa pun, Anda tidak akan berhasil menambahkan referensi ke pustaka iklan Microsoft dalam langkah-langkah berikut. Untuk informasi selengkapnya, lihat Kesalahan referensi yang disebabkan oleh penargetan CPU apa pun dalam proyek Anda.

  3. Tambahkan referensi ke Microsoft Advertising SDK di proyek Anda:

    1. Dari jendela Penjelajah Solusi, klik kanan Referensi, dan pilih Tambahkan Referensi...
    2. Di Pengelola Referensi, perluas Universal Windows, klik Ekstensi, lalu pilih kotak centang di samping Microsoft Advertising SDK untuk JavaScript (Versi 10.0).
    3. Di Pengelola Referensi, klik OK.

  4. Buka file index.html (atau file html lainnya yang sesuai untuk proyek Anda).

  5. Di bagian <kepala> , setelah referensi JavaScript proyek default.css dan main.js, tambahkan referensi ke ad.js.

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

    Catatan

    Baris ini harus ditempatkan di bagian <kepala> setelah disertakan main.js; jika tidak, Anda akan mengalami kesalahan saat membangun proyek Anda.

  6. Ubah bagian <isi> dalam file default.html (atau file html lainnya yang sesuai untuk proyek Anda) untuk menyertakan div untuk AdControl. Tetapkan properti applicationId dan adUnitIdadControl ke nilai unit iklan pengujian. Sesuaikan juga tinggi dan lebar sehingga kontrol adalah salah satu ukuran iklan yang didukung untuk iklan banner.

    Catatan

    Setiap AdControl memiliki unit iklan terkait yang digunakan oleh layanan kami untuk menayangkan iklan ke kontrol, dan setiap unit iklan terdiri dari ID unit iklan dan ID aplikasi. Dalam langkah-langkah ini, Anda menetapkan nilai ID unit iklan pengujian dan ID aplikasi ke kontrol Anda. Nilai pengujian ini hanya dapat digunakan dalam versi pengujian aplikasi Anda. Sebelum memublikasikan aplikasi ke Bursa, Anda harus mengganti nilai pengujian ini dengan nilai langsung dari Pusat Mitra.

    <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. Kompilasi dan jalankan aplikasi untuk melihatnya dengan iklan.

Contoh berikut menunjukkan index.html lengkap untuk aplikasi sederhana.

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

Membuat AdControl secara terprogram di JavaScript

Langkah-langkah sebelumnya menunjukkan cara mendeklarasikan AdControl di markup HTML Anda. Atau, Anda dapat membuat AdControl secara terprogram menggunakan JavaScript. Contoh ini mengasumsikan bahwa Anda menggunakan div yang ada di HTML Anda dengan 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;

Contoh ini mengasumsikan bahwa Anda telah mendeklarasikan metode penanganan aktivitas bernama myAdError, myAdRefreshed, dan myAdEngagedChanged.

Jika Anda menggunakan kode ini dan tidak melihat iklan, Anda dapat mencoba menyisipkan atribut posisi:relatif di div yang berisi AdControl. Ini akan menggantikan pengaturan default IFrame. Iklan akan ditampilkan dengan benar, kecuali jika tidak ditampilkan karena nilai atribut ini. Perhatikan bahwa unit iklan baru mungkin tidak tersedia hingga 30 menit.

Catatan

Nilai applicationId dan adUnitId yang ditunjukkan dalam contoh ini adalah nilai mode pengujian. Anda harus mengganti nilai-nilai ini dengan nilai langsung dari Pusat Mitra sebelum mengirimkan aplikasi Anda untuk pengiriman.

Merilis aplikasi Anda dengan iklan langsung

  1. Pastikan Anda menggunakan iklan banner di aplikasi Anda mengikuti panduan kami untuk iklan banner.

  2. Di Pusat Mitra, buka halaman Iklan dalam aplikasi dan buat unit iklan. Untuk jenis unit iklan, tentukan Banner. Catat ID unit iklan dan ID aplikasi.

    Catatan

    Nilai ID aplikasi untuk unit iklan pengujian dan unit iklan UWP langsung memiliki format yang berbeda. Nilai ID aplikasi pengujian adalah GUID. Saat Anda membuat unit iklan UWP langsung di Pusat Mitra, nilai ID aplikasi untuk unit iklan selalu cocok dengan ID Toko untuk aplikasi Anda (contoh nilai ID Store terlihat seperti 9NBLGGH4R315).

  3. Anda dapat mengaktifkan mediasi iklan secara opsional untuk AdControl dengan mengonfigurasi pengaturan di bagian Pengaturan mediasi di halaman Iklan dalam aplikasi . Mediasi iklan memungkinkan Anda memaksimalkan kemampuan pendapatan iklan dan promosi aplikasi dengan menampilkan iklan dari beberapa jaringan iklan, termasuk iklan dari jaringan iklan berbayar lainnya seperti Taboola dan Smaato dan iklan untuk kampanye promosi aplikasi Microsoft.

  4. Dalam kode Anda, ganti nilai unit iklan pengujian (applicationId dan adUnitId) dengan nilai langsung yang Anda buat di Pusat Mitra.

  5. Kirimkan aplikasi Anda ke Toko menggunakan Pusat Mitra.

  6. Tinjau laporan performa iklan Anda di Pusat Mitra.

Mengelola unit iklan untuk beberapa kontrol iklan di aplikasi Anda

Anda dapat menggunakan beberapa objek AdControl dalam satu aplikasi (misalnya, setiap halaman di aplikasi Anda mungkin menghosting objek AdControl yang berbeda). Dalam skenario ini, kami sarankan Anda menetapkan unit iklan yang berbeda untuk setiap kontrol. Menggunakan unit iklan yang berbeda untuk setiap kontrol memungkinkan Anda mengonfigurasi pengaturan mediasi secara terpisah dan mendapatkan data pelaporan diskrit untuk setiap kontrol. Ini juga memungkinkan layanan kami untuk lebih mengoptimalkan iklan yang kami sajikan ke aplikasi Anda.

Penting

Anda hanya dapat menggunakan setiap unit iklan dalam satu aplikasi. Jika Anda menggunakan unit iklan di lebih dari satu aplikasi, iklan tidak akan ditayangkan untuk unit iklan tersebut.