Iklan interstisial

Peringatan

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

Panduan ini menunjukkan cara menyertakan iklan interstisial di aplikasi dan game Platform Windows Universal (UWP) untuk Windows 10 dan Windows 11. Untuk contoh lengkap proyek yang menunjukkan cara menambahkan iklan interstisial ke aplikasi JavaScript/HTML dan aplikasi XAML menggunakan C# dan C++, lihat sampel iklan di GitHub.

Apa itu iklan interstisial?

Tidak seperti iklan banner standar, yang terbatas pada sebagian UI dalam aplikasi atau game, iklan interstisial ditampilkan di seluruh layar. Dua bentuk dasar sering digunakan dalam game.

• Dengan iklan Paywall , pengguna harus menonton iklan secara berkala. Misalnya antara level game:

  

• Dengan iklan Berbasis Hadiah, pengguna secara eksplisit mencari keuntungan, seperti petunjuk atau waktu tambahan untuk menyelesaikan level, dan menginisialisasi iklan melalui antarmuka pengguna aplikasi.

Kami menyediakan dua jenis iklan interstisial untuk digunakan di aplikasi dan game Anda: iklan video interstisial dan iklan banner interstisial.

Catatan

API untuk iklan interstisial tidak menangani antarmuka pengguna apa pun kecuali pada saat pemutaran video. Lihat praktik terbaik interstisial untuk panduan tentang apa yang harus dilakukan, dan hindari, saat Anda mempertimbangkan cara mengintegrasikan iklan interstisial di aplikasi Anda.

Prasyarat

• Instal Microsoft Advertising SDK dengan Visual Studio 2015 atau rilis Visual Studio yang lebih baru. Untuk petunjuk penginstalan, lihat artikel ini.

Mengintegrasikan iklan interstisial ke dalam aplikasi Anda

Untuk menampilkan iklan interstisial di aplikasi Anda, ikuti petunjuk jenis proyek:

• XAML/.NET
• HTML/JavaScript
• C++ (Interop DirectX)

XAML/.NET

Bagian ini menyediakan contoh C#, tetapi Visual Basic dan C++ juga didukung untuk proyek XAML/.NET. Untuk contoh kode C# lengkap, lihat Kode sampel iklan interstisial di C#.

1. Buka proyek Anda di Visual Studio.

   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 menargetkan 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 XAML (Versi 10.0).
   3. Di Manajer Referensi, klik OK.

4. Dalam file kode yang sesuai di aplikasi Anda (misalnya, di MainPage.xaml.cs atau file kode untuk beberapa halaman lain), tambahkan referensi namespace berikut.

   using Microsoft.Advertising.WinRT.UI;
   

5. Di lokasi yang sesuai di aplikasi Anda (misalnya, di MainPage atau beberapa halaman lain), deklarasikan objek InterstitialAd dan beberapa bidang string yang mewakili ID aplikasi dan ID unit iklan untuk iklan interstisial Anda. Contoh kode berikut menetapkan myAppId bidang dan myAdUnitId ke nilai pengujian untuk iklan interstisial.

   Catatan

   Setiap InterstitialAd 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 Store, Anda harus mengganti nilai pengujian ini dengan nilai langsung dari Pusat Mitra.

   InterstitialAd myInterstitialAd = null;
   string myAppId = "d25517cb-12d4-4699-8bdc-52040c712cab";
   string myAdUnitId = "test";
   

6. Dalam kode yang berjalan pada startup (misalnya, di konstruktor untuk halaman), buat instans objek InterstitialAd dan kawat penanganan aktivitas untuk peristiwa objek.

   myInterstitialAd = new InterstitialAd();
   myInterstitialAd.AdReady += MyInterstitialAd_AdReady;
   myInterstitialAd.ErrorOccurred += MyInterstitialAd_ErrorOccurred;
   myInterstitialAd.Completed += MyInterstitialAd_Completed;
   myInterstitialAd.Cancelled += MyInterstitialAd_Cancelled;
   

7. Jika Anda ingin menampilkan iklan video interstisial: Sekitar 30-60 detik sebelum memerlukan iklan, gunakan metode RequestAd untuk mengambil iklan sebelumnya. Ini memungkinkan cukup waktu untuk meminta dan menyiapkan iklan sebelum harus ditampilkan. Pastikan untuk menentukan AdType.Video untuk jenis iklan.

   myInterstitialAd.RequestAd(AdType.Video, myAppId, myAdUnitId);
   

   Jika Anda ingin menampilkan iklan banner interstisial: Sekitar 5-8 detik sebelum Anda memerlukan iklan, gunakan metode RequestAd untuk mengambil iklan sebelumnya. Ini memungkinkan cukup waktu untuk meminta dan menyiapkan iklan sebelum harus ditampilkan. Pastikan untuk menentukan AdType.Display untuk jenis iklan.

   myInterstitialAd.RequestAd(AdType.Display, myAppId, myAdUnitId);
   

8. Pada titik dalam kode Anda di mana Anda ingin menampilkan video interstisial atau iklan spanduk interstisial, konfirmasikan bahwa InterstitialAd siap ditampilkan dan kemudian menunjukkannya dengan menggunakan metode Tampilkan .

   if (InterstitialAdState.Ready == myInterstitialAd.State)
   {
       myInterstitialAd.Show();
   }
   

9. Tentukan penanganan aktivitas untuk objek InterstitialAd .

   void MyInterstitialAd_AdReady(object sender, object e)
   {
       // Your code goes here.
   }
   
   void MyInterstitialAd_ErrorOccurred(object sender, AdErrorEventArgs e)
   {
       // Your code goes here.
   }
   
   void MyInterstitialAd_Completed(object sender, object e)
   {
       // Your code goes here.
   }
   
   void MyInterstitialAd_Cancelled(object sender, object e)
   {
       // Your code goes here.
   }
   

10. Buat dan uji aplikasi Anda untuk mengonfirmasi bahwa aplikasi tersebut menampilkan iklan pengujian.

HTML/JavaScript

Instruksi berikut mengasumsikan Anda telah membuat proyek Universal Windows untuk JavaScript di Visual Studio dan menargetkan CPU tertentu. Untuk sampel kode lengkap, lihat Kode sampel iklan interstisial di JavaScript.

1. Buka proyek Anda di Visual Studio.

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 menargetkan 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 for JavaScript (Versi 10.0).
   3. Di Manajer Referensi, klik OK.

4. Di bagian <kepala> file HTML dalam proyek, setelah referensi JavaScript proyek default.css dan default.js, tambahkan referensi ke ad.js.

   <script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
   

5. Dalam file .js dalam proyek Anda, deklarasikan objek InterstitialAd dan beberapa bidang yang berisi ID aplikasi dan ID unit iklan untuk iklan interstisial Anda. Contoh kode berikut menetapkan applicationId bidang dan adUnitId ke nilai pengujian untuk iklan interstisial.

   Catatan

   Setiap InterstitialAd 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 Store, Anda harus mengganti nilai pengujian ini dengan nilai langsung dari Pusat Mitra.

   var interstitialAd = null;
   var applicationId = "d25517cb-12d4-4699-8bdc-52040c712cab";
   var adUnitId = "test";
   

6. Dalam kode yang berjalan pada startup (misalnya, di konstruktor untuk halaman), buat objek InterstitialAd dan kawat penanganan aktivitas untuk objek.

   interstitialAd = new MicrosoftNSJS.Advertising.InterstitialAd();
   interstitialAd.onErrorOccurred = errorOccurredHandler;
   interstitialAd.onAdReady = adReadyHandler;
   interstitialAd.onCancelled = cancelledHandler;
   interstitialAd.onCompleted = completedHandler;
   

7. Jika Anda ingin menampilkan iklan video interstisial: Sekitar 30-60 detik sebelum memerlukan iklan, gunakan metode RequestAd untuk mengambil iklan sebelumnya. Ini memungkinkan cukup waktu untuk meminta dan menyiapkan iklan sebelum harus ditampilkan. Pastikan untuk menentukan InterstitialAdType.video untuk jenis iklan.

   if (interstitialAd) {
       interstitialAd.requestAd(MicrosoftNSJS.Advertising.InterstitialAdType.video, applicationId, adUnitId);
   }
   

   Jika Anda ingin menampilkan iklan banner interstisial: Sekitar 5-8 detik sebelum Anda memerlukan iklan, gunakan metode RequestAd untuk mengambil iklan sebelumnya. Ini memungkinkan cukup waktu untuk meminta dan menyiapkan iklan sebelum harus ditampilkan. Pastikan untuk menentukan InterstitialAdType.display untuk jenis iklan.

   if (interstitialAd) {
       interstitialAd.requestAd(MicrosoftNSJS.Advertising.InterstitialAdType.display, applicationId, adUnitId);
   }
   

8. Pada titik kode tempat Anda ingin menampilkan iklan, konfirmasikan bahwa InterstitialAd siap ditampilkan lalu tampilkan dengan menggunakan metode Tampilkan .

   if (interstitialAd && interstitialAd.state === MicrosoftNSJS.Advertising.InterstitialAdState.ready) {
       interstitialAd.show();
   }
   

9. Tentukan penanganan aktivitas untuk objek InterstitialAd .

   function adReadyHandler(sender) {
     // Your code goes here.
   }
   
   function errorOccurredHandler(sender, args) {
     // Your code goes here.
   }
   
   function completedHandler(sender) {
     // Your code goes here.
   }
   
   function cancelledHandler(sender) {
     // Your code goes here.
   }
   

10. Buat dan uji aplikasi Anda untuk mengonfirmasi bahwa aplikasi tersebut menampilkan iklan pengujian.

C++ (Interop DirectX)

Sampel ini mengasumsikan Anda telah membuat proyek C++ DirectX dan Aplikasi XAML (Universal Windows) di Visual Studio dan menargetkan arsitektur CPU tertentu.  

1. Buka proyek Anda di Visual Studio.

2. 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 XAML (Versi 10.0).
   3. Di Manajer Referensi, klik OK.

3. Dalam file header yang sesuai untuk aplikasi Anda (misalnya, DirectXPage.xaml.h), deklarasikan objek InterstitialAd dan metode penanganan aktivitas terkait.

   Microsoft::Advertising::WinRT::UI::InterstitialAd^ m_interstitialAd;
   void OnAdReady(Object^ sender, Object^ args);
   void OnAdCompleted(Object^ sender, Object^ args);
   void OnAdCancelled(Object^ sender, Object^ args);
   void OnAdError(Object^ sender, Microsoft::Advertising::WinRT::UI::AdErrorEventArgs^ args);
   

4. Dalam file header yang sama, deklarasikan beberapa bidang string yang mewakili ID aplikasi dan ID unit iklan untuk iklan interstisial Anda. Contoh kode berikut menetapkan myAppId bidang dan myAdUnitId ke nilai pengujian untuk iklan interstisial.

   Catatan

   Setiap InterstitialAd 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 Store, Anda harus mengganti nilai pengujian ini dengan nilai langsung dari Pusat Mitra.

   Platform::String^ myAppId = L"d25517cb-12d4-4699-8bdc-52040c712cab";
   Platform::String^ myAdUnitId = L"test";
   

5. Dalam file .cpp tempat Anda ingin menambahkan kode untuk menampilkan iklan interstisial, tambahkan referensi namespace berikut. Contoh berikut mengasumsikan Anda menambahkan kode ke file DirectXPage.xaml.cpp di aplikasi Anda.

   using namespace Microsoft::Advertising::WinRT::UI;
   

6. Dalam kode yang berjalan pada startup (misalnya, di konstruktor untuk halaman), buat instans objek InterstitialAd dan kawat penanganan aktivitas untuk peristiwa objek. Dalam contoh berikut, InterstitialAdSamplesCpp adalah namespace untuk proyek Anda; ubah nama ini seperlunya untuk kode Anda.

   m_interstitialAd = ref new InterstitialAd();         
   m_interstitialAd->AdReady += ref new Windows::Foundation::EventHandler<Platform::Object ^>
       (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdReady);
   m_interstitialAd->Completed += ref new Windows::Foundation::EventHandler<Platform::Object ^>
       (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdCompleted);
   m_interstitialAd->Cancelled += ref new Windows::Foundation::EventHandler<Platform::Object ^>
       (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdCancelled);
   m_interstitialAd->ErrorOccurred += ref new
       Windows::Foundation::EventHandler<Microsoft::Advertising::WinRT::UI::AdErrorEventArgs ^>
       (this, &InterstitialAdSamplesCpp::DirectXPage::OnAdError);
   

7. Jika Anda ingin menampilkan iklan video interstisial: Sekitar 30-60 detik sebelum Anda memerlukan iklan interstisial, gunakan metode RequestAd untuk mengambil iklan sebelumnya. Ini memungkinkan cukup waktu untuk meminta dan menyiapkan iklan sebelum harus ditampilkan. Pastikan untuk menentukan AdType::Video untuk jenis iklan.

   m_interstitialAd->RequestAd(AdType::Video, myAppId, myAdUnitId);
   

   Jika Anda ingin menampilkan iklan banner interstisial: Sekitar 5-8 detik sebelum Anda memerlukan iklan, gunakan metode RequestAd untuk mengambil iklan sebelumnya. Ini memungkinkan cukup waktu untuk meminta dan menyiapkan iklan sebelum harus ditampilkan. Pastikan untuk menentukan AdType::D isplay untuk jenis iklan.

   m_interstitialAd->RequestAd(AdType::Display, myAppId, myAdUnitId);
   

8. Pada titik kode tempat Anda ingin menampilkan iklan, konfirmasikan bahwa InterstitialAd siap ditampilkan lalu tampilkan dengan menggunakan metode Tampilkan .

   if ((InterstitialAdState::Ready == m_interstitialAd->State))
   {
       m_interstitialAd->Show();
   }
   

9. Tentukan penanganan aktivitas untuk objek InterstitialAd .

   void DirectXPage::OnAdReady(Object^ sender, Object^ args)
   {
       // Your code goes here.
   }
   
   
   void DirectXPage::OnAdCompleted(Object^ sender, Object^ args)
   {
       // Your code goes here.
   }
   
   void DirectXPage::OnAdCancelled(Object^ sender, Object^ args)
   {
       // Your code goes here.
   }
   
   void DirectXPage::OnAdError(Object^ sender, Microsoft::Advertising::WinRT::UI::AdErrorEventArgs^ args)
   {
       // Your code goes here.
   }
   

10. Buat dan uji aplikasi Anda untuk mengonfirmasi bahwa aplikasi tersebut menampilkan iklan pengujian.

Merilis aplikasi Anda dengan iklan langsung

1. Pastikan penggunaan iklan interstisial di aplikasi Anda mengikuti panduan kami untuk iklan interstisial.

2. Di Pusat Mitra, buka halaman Iklan dalam aplikasi dan buat unit iklan. Untuk jenis unit iklan, pilih Interstisial video atau Interstisial Banner, tergantung pada jenis iklan interstisial apa yang Anda tampilkan. 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 Toko terlihat seperti 9NBLGGH4R315).

3. Anda dapat mengaktifkan mediasi iklan secara opsional untuk InterstitialAd 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 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 interstisial di aplikasi Anda

Anda dapat menggunakan beberapa kontrol InterstitialAd dalam satu aplikasi. 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 mengoptimalkan iklan yang kami sajikan dengan lebih baik 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.

Topik terkait

• Panduan untuk iklan interstisial
• Kode sampel iklan interstisial di C#
• Kode sampel iklan interstisial di JavaScript
• Sampel iklan di GitHub
• Menyiapkan unit iklan untuk aplikasi Anda