Menjalankan kampanye iklan menggunakan layanan Store

Gunakan API promosi Microsoft Store untuk mengelola kampanye iklan promosi secara terprogram untuk aplikasi yang terdaftar di akun Pusat Mitra organisasi Anda atau Anda. API ini memungkinkan Anda membuat, memperbarui, dan memantau kampanye Dan aset terkait lainnya seperti penargetan dan materi iklan. API ini sangat berguna bagi pengembang yang membuat kampanye dalam volume besar, dan yang ingin melakukannya tanpa menggunakan Pusat Mitra. API ini menggunakan Azure Active Directory (Azure AD) untuk mengautentikasi panggilan dari aplikasi atau layanan Anda.

Langkah-langkah berikut ini menjelaskan proses end-to-end:

1. Pastikan Anda telah menyelesaikan semua prasyarat.
2. Sebelum Anda memanggil metode di API promosi Microsoft Store, dapatkan token akses Microsoft Azure ACTIVE Directory. Setelah mendapatkan token, Anda memiliki waktu 60 menit untuk menggunakan token ini dalam panggilan ke API promosi Microsoft Store sebelum token kedaluwarsa. Setelah token kedaluwarsa, Anda dapat menghasilkan token baru.
3. Hubungi API promosi Microsoft Store.

Anda juga dapat membuat dan mengelola kampanye iklan menggunakan Pusat Mitra, dan kampanye iklan apa pun yang Anda buat secara terprogram melalui API promosi Microsoft Store juga dapat diakses di Pusat Mitra. Untuk informasi selengkapnya tentang mengelola kampanye iklan di Pusat Mitra, lihat Membuat kampanye iklan untuk aplikasi Anda.

Catatan

Setiap pengembang dengan akun Pusat Mitra dapat menggunakan API promosi Microsoft Store untuk mengelola kampanye iklan untuk aplikasi mereka. Agensi media juga dapat meminta akses ke API ini untuk menjalankan kampanye iklan atas nama pengiklan mereka. Jika Anda adalah agensi media yang ingin tahu lebih banyak tentang API ini atau meminta akses ke API ini, kirim permintaan Anda ke storepromotionsapi@microsoft.com.

Langkah 1: Lengkapi prasyarat untuk menggunakan API promosi Microsoft Store

Sebelum Anda mulai menulis kode untuk memanggil API promosi Microsoft Store, pastikan Anda telah menyelesaikan prasyarat berikut.

• Sebelum berhasil membuat dan memulai kampanye iklan menggunakan API ini, Anda harus terlebih dahulu membuat satu kampanye iklan berbayar menggunakan halaman Kampanye iklan di Pusat Mitra, dan Anda harus menambahkan setidaknya satu instrumen pembayaran di halaman ini. Setelah melakukan ini, Anda akan berhasil membuat jalur pengiriman yang dapat ditagih untuk kampanye iklan menggunakan API ini. Baris pengiriman untuk kampanye iklan yang Anda buat menggunakan API ini akan secara otomatis menagih instrumen pembayaran default yang dipilih di halaman Kampanye iklan di Pusat Mitra.

• Anda (atau organisasi Anda) harus memiliki direktori Azure Active Directory dan harus memiliki izin Administrator perusahaan untuk direktori tersebut. Jika sudah menggunakan Microsoft 365 atau layanan bisnis lainnya dari Microsoft, Anda sudah memiliki direktori Azure Active Directory. Jika tidak, Anda dapat membuat Azure AD baru di Pusat Mitra tanpa biaya tambahan.

• Anda harus mengaitkan aplikasi Microsoft Azure AD dengan akun Pusat Mitra Anda, mengambil ID penyewa dan ID klien untuk aplikasi dan membuat kunci. Aplikasi Microsoft Azure ACTIVE Directory mewakili aplikasi atau layanan tempat Anda ingin memanggil API promosi Microsoft Store. Anda memerlukan ID penyewa, ID klien, dan kunci untuk mendapatkan token akses Azure Active Directory yang Anda berikan ke API.

  Catatan

  Anda hanya perlu melakukan tugas ini satu kali. Setelah memiliki ID penyewa, ID klien, dan kunci, Anda dapat menggunakannya kembali kapan saja Anda perlu untuk membuat token akses Azure Active Directory baru.

Untuk mengaitkan aplikasi Microsoft Azure AD dengan akun Pusat Mitra Anda dan mengambil nilai yang diperlukan:

1. Di Pusat Mitra, kaitkan akun Pusat Mitra organisasi dengan direktori Azure Active Directory organisasi Anda.

2. Selanjutnya, dari halaman Pengguna di bagian Pengaturan akun di Pusat Mitra, tambahkan aplikasi Azure ACTIVE Directory yang mewakili aplikasi atau layanan yang akan Anda gunakan untuk mengelola kampanye promosi untuk akun Pusat Mitra Anda. Pastikan Anda menetapkan aplikasi ini sebagai peranManajer. Jika aplikasi belum ada di direktori Azure Active Directory, Anda dapat membuat aplikasi Azure Active Directory baru di Pusat Mitra.

3. Kembali ke halaman Pengguna, klik nama aplikasi Azure Active Directory Anda untuk masuk ke pengaturan aplikasi, dan salin nilai ID Penyewa dan ID Klien.

4. Klik Tambahkan kunci baru. Pada layar berikut, salin nilai Kunci. Anda tidak akan dapat mengakses info ini lagi setelah meninggalkan halaman ini. Untuk informasi selengkapnya, lihat Mengelola kunci untuk aplikasi Azure Active Directory.

Langkah 2: Mendapatkan token akses Azure Active Directory

Sebelum memanggil salah satu metode di API promosi Microsoft Store, Anda harus terlebih dahulu mendapatkan token akses Microsoft Azure AD yang Anda teruskan ke header Otorisasi dari setiap metode di API. Setelah mendapatkan token akses, Anda memiliki waktu 60 menit untuk menggunakan token akses sebelum masa berlakunya habis. Setelah token kedaluwarsa, Anda dapat merefresh token sehingga Anda dapat terus menggunakannya dalam panggilan lebih lanjut ke API.

Untuk mendapatkan token akses, ikuti instruksi dalam Panggilan Layanan ke Layanan Menggunakan Kredensial Klien untuk mengirim HTTP POST ke https://login.microsoftonline.com/<tenant_id>/oauth2/token titik akhir. Berikut adalah contoh permintaan.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://manage.devcenter.microsoft.com

Untuk nilai tenant_id di POST URI dan parameter client_id dan client_secret, tentukan ID penyewa, ID klien, dan kunci untuk aplikasi yang Anda ambil dari Pusat Mitra di bagian sebelumnya. Untuk parameter sumber daya, Anda harus menentukan https://manage.devcenter.microsoft.com.

Setelah token akses kedaluwarsa, Anda dapat merefreshnya dengan mengikuti instruksi di sini.

Langkah 3: Panggil API promosi Microsoft Store

Setelah Anda memiliki token akses Azure ACTIVE Directory, Anda siap untuk memanggil API promosi Microsoft Store. Anda harus meneruskan token akses ke header Otorisasi dari setiap metode.

Dalam konteks API promosi Microsoft Store, kampanye iklan terdiri dari objek kampanye yang berisi informasi tingkat tinggi tentang kampanye, dan objek tambahan yang mewakili baris pengiriman, profil penargetan, dan materi iklan untuk kampanye iklan. API mencakup berbagai set metode yang dikelompokkan menurut jenis objek ini. Untuk membuat kampanye, Anda biasanya memanggil metode POST yang berbeda untuk setiap objek ini. API juga menyediakan metode GET yang dapat Anda gunakan untuk mengambil objek dan metode PUT apa pun yang dapat Anda gunakan untuk mengedit kampanye, jalur pengiriman, dan menargetkan objek profil.

Untuk informasi selengkapnya tentang objek ini dan metode terkaitnya, lihat tabel berikut ini.

Objek	Deskripsi
Kampanye	Objek ini mewakili kampanye iklan, dan berada di bagian atas hierarki model objek untuk kampanye iklan. Objek ini mengidentifikasi jenis kampanye yang Anda jalankan (berbayar, rumah, atau komunitas), tujuan kampanye, jalur pengiriman untuk kampanye, dan detail lainnya. Setiap kampanye hanya dapat dikaitkan dengan satu aplikasi. Untuk informasi selengkapnya tentang metode yang terkait dengan objek ini, lihat Mengelola kampanye iklan. Catatan Setelah membuat kampanye iklan, Anda dapat mengambil data performa untuk kampanye dengan menggunakan metode Dapatkan data performa kampanye iklan di API analitik Microsoft Store.
Baris pengiriman	Setiap kampanye memiliki satu atau beberapa jalur penayangan yang digunakan untuk membeli inventori dan menayangkan iklan Anda. Untuk setiap jalur pengiriman, Anda dapat menetapkan penargetan, menetapkan harga penawaran Anda, dan memutuskan berapa banyak yang ingin Anda belanjakan dengan menetapkan anggaran dan menautkan ke materi iklan yang ingin Anda gunakan. Untuk informasi selengkapnya tentang metode yang terkait dengan objek ini, lihat Mengelola baris pengiriman untuk kampanye iklan.
Menargetkan profil	Setiap jalur pengiriman memiliki satu profil penargetan yang menentukan pengguna, geografi, dan jenis inventori yang ingin Anda targetkan. Profil penargetan dapat dibuat sebagai templat dan dibagikan di seluruh baris pengiriman. Untuk informasi selengkapnya tentang metode yang terkait dengan objek ini, lihat Mengelola profil penargetan untuk kampanye iklan.
Materi Iklan	Setiap jalur penayangan memiliki satu atau beberapa materi iklan yang mewakili iklan yang ditampilkan kepada pelanggan sebagai bagian dari kampanye. Materi iklan dapat dikaitkan dengan satu atau beberapa jalur pengiriman, bahkan di seluruh kampanye iklan, asalkan selalu mewakili aplikasi yang sama. Untuk informasi selengkapnya tentang metode yang terkait dengan objek ini, lihat Mengelola materi iklan untuk kampanye iklan.

Diagram berikut mengilustrasikan hubungan antara kampanye, jalur pengiriman, profil penargetan, dan materi iklan.

Contoh kode

Contoh kode berikut menunjukkan cara mendapatkan token akses Microsoft Azure ACTIVE Directory dan memanggil API promosi Microsoft Store dari aplikasi konsol C#. Untuk menggunakan contoh kode ini, tetapkan variabel tenantId, clientId, clientSecret, dan appID ke nilai yang sesuai untuk skenario Anda. Contoh ini memerlukan paket Json.NET dari Newtonsoft untuk mendeserialisasi data JSON yang dikembalikan oleh API promosi Microsoft Store.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace TestPromotionsAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            string tenantId = "<your tenant ID>";
            string clientId = "<your client ID>";
            string clientSecret = "<your secret>";

            string scope = "https://manage.devcenter.microsoft.com";

            // Retrieve an Azure AD access token
            string accessToken = GetClientCredentialAccessToken(
                    tenantId,
                    clientId,
                    clientSecret,
                    scope).Result;

            int pageSize = 100;
            int startPageIndex = 0;

            // This is your app's Store ID. This ID is available on
            // the App identity page of the Dev Center dashboard.
            string appID = "<your app's Store ID>";


            // Call the Windows Store promotions API
            CallPromotionsAPI(accessToken, appID, pageSize, startPageIndex);

            Console.Read();
        }

        private static void CallPromotionsAPI(string accessToken, string appID, int fetch, int skip)
        {
            string requestURI;

            // Get ad campaigns.
            requestURI = string.Format(
                "https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?applicationId={0}&fetch={1}&skip={2}&campaignSetSortColumn=createdDateTime",
                appID, fetch, skip);

            HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, requestURI);
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            WebRequestHandler handler = new WebRequestHandler();
            HttpClient httpClient = new HttpClient(handler);

            HttpResponseMessage response = httpClient.SendAsync(requestMessage).Result;

            Console.WriteLine(response);
            Console.WriteLine(response.Content.ReadAsStringAsync().Result);

            response.Dispose();
        }

        public static async Task<string> GetClientCredentialAccessToken(string tenantId, string clientId, string clientSecret, string scope)
        {
            string tokenEndpointFormat = "https://login.microsoftonline.com/{0}/oauth2/token";
            string tokenEndpoint = string.Format(tokenEndpointFormat, tenantId);

            dynamic result;
            using (HttpClient client = new HttpClient())
            {
                string tokenUrl = tokenEndpoint;
                using (
                    HttpRequestMessage request = new HttpRequestMessage(
                        HttpMethod.Post,
                        tokenUrl))
                {
                    string content =
                        string.Format(
                            "grant_type=client_credentials&client_id={0}&client_secret={1}&resource={2}",
                            clientId,
                            clientSecret,
                            scope);

                    request.Content = new StringContent(content, Encoding.UTF8, "application/x-www-form-urlencoded");

                    using (HttpResponseMessage response = await client.SendAsync(request))
                    {
                        string responseContent = await response.Content.ReadAsStringAsync();
                        result = JsonConvert.DeserializeObject(responseContent);
                    }
                }
            }

            return result.access_token;
        }
    }
}

Topik terkait

• Mengelola kampanye iklan
• Mengelola jalur pengiriman untuk kampanye iklan
• Mengelola profil penargetan untuk kampanye iklan
• Mengelola materi iklan untuk kampanye iklan
• Mendapatkan data performa kampanye iklan