この記事では、 NativeAdRequest と NativeAdResponse を使用して、Android アプリにネイティブ広告を表示する方法について説明します。
概要
ネイティブ広告を使用すると、アプリのデザインに一致するビューで広告アセットをレンダリングできます。 このワークフローをサポートするために、Android SDK は以下のクラス、インターフェイス、およびメソッドを公開しています。
-
NativeAdRequestプレースメントの広告を読み込み、NativeAdRequestListenerは結果を受け取ります。 -
NativeAdResponse成功した要求によって返されるネイティブ アセットを提供します。 -
NativeAdSDK.registerTracking()レンダリングされたコンテナーを応答に関連付け、NativeAdEventListenerはインプレッション イベントとクリック イベントを受け取ります。
標準 SDK フローでは、要求を作成してロードし、応答からアセットをレンダリングしてから、追跡用にコンテナーを登録します。
- 広告の表示中は、要求、応答、コンテナーへの参照を保持します。
- 別のネイティブ広告に再利用する前に、およびビューが破棄された場合は、コンテナーの登録を解除してください。
ネイティブ広告応答で返されるアセットをカスタマイズするには、「 OpenRTB ネイティブを使用して特定のアセットを要求 する」または 「ネイティブ アセンブリを使用して特定のアセットを要求する」を参照してください。
注:
ネイティブ インプレッション カウントの詳細については、「 インプレッション カウント方法」を参照してください。
ネイティブ広告を要求する
NativeAdRequest では、次の方法を使用します。
| メソッド | 説明 |
|---|---|
NativeAdRequest(Context context, String placementId) |
プレースメント ID のネイティブ広告要求を作成します。 |
void setListener(NativeAdRequestListener listener) |
要求結果を受け取るリスナーを設定します。 |
void loadAd() |
1 つのネイティブ広告を読み込みます。 |
標準のネイティブ応答データにアクセスする
標準のネイティブ フローを使用するには、setOpenRTBAssets() を呼び出さずにNativeAdRequestを読み込みます。
NativeAdResponse 選択した広告で使用できるアセットと関連するメタデータが含まれます。
NativeAdResponse では、次の方法を使用します。
| Asset | メソッド | 既定値 | 説明 |
|---|---|---|---|
| タイトル | getTitle() |
空の文字列 | 広告タイトルを返します。 |
| 後援 | getSponsoredBy() |
空の文字列 | 広告主またはスポンサー名を返します。 |
| Body text | getDescription() |
空の文字列 | プライマリ広告の説明文を返します。 |
| 追加の説明 | getAdditionalDescription() |
空の文字列 | 追加の広告説明文を返します。 |
| 実施すべき内容 | getCallToAction() |
空の文字列 | 行動喚起コントロールのテキストを返します。 |
| メイン画像の URL | getImageUrl() |
空の文字列 | メイン イメージを読み込むための URL を返します。 |
| メイン画像のサイズ | getImageSize() |
幅と高さは -1 |
メイン イメージのサイズを返します。 |
| メイン画像 | getImage() |
null |
プリロードされたメイン イメージを返します。 「 イメージ読み込みの構成」を参照してください。 |
| アイコン画像の URL | getIconUrl() |
空の文字列 | アイコン イメージを読み込むための URL を返します。 |
| アイコン画像のサイズ | getIconSize() |
幅と高さは -1 |
アイコン イメージのサイズを返します。 |
| アイコンの画像 | getIcon() |
null |
プリロードされたアイコン イメージを返します。 「 イメージ読み込みの構成」を参照してください。 |
| 評価 | getAdStarRating() |
null |
広告対象の製品やアプリのレーティング値と尺度を返します。 |
| プライバシー URL | getPrivacyLink() |
空の文字列 | 広告に指定されたプライバシー情報の URL (使用可能な場合) を返します。 |
レジスタ追跡
NativeAdResponse からアセットをレンダリングした後、NativeAdSDK を使用して、インプレッションとクリックのトラッキング用にコンテナーを登録します。
| メソッド | 説明 |
|---|---|
void registerTracking( |
レンダリングされたコンテナーをインプレッション トラッキング用に登録し、コンテナーをクリック可能にします。 |
void registerTracking( |
レンダリングされたコンテナーをインプレッション トラッキング用に登録し、リストされたビューをクリック可能にします。 |
void registerTracking( |
味方の障害物との追跡を登録します。 |
void registerTracking( |
特定のクリック可能なビューと友好的な障害物を使用して追跡を登録します。 |
void unRegisterTracking(View container) |
登録済みコンテナーの追跡を停止し、そのビューアビリティ セッションを完了します。 |
味方の障害物を登録する方法については、「 Android での視認性測定」を参照してください。
例
class NativeAdActivity : AppCompatActivity(), NativeAdRequestListener, NativeAdEventListener {
private lateinit var nativeAdRequest: NativeAdRequest
private var nativeAdResponse: NativeAdResponse? = null
private lateinit var nativeContainer: View
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_native)
nativeContainer = findViewById(R.id.native_ad_container)
nativeAdRequest = NativeAdRequest(this, "123456") // Create a request for the placement ID
nativeAdRequest.listener = this // Set the request listener
nativeAdRequest.loadAd() // Load the ad
}
override fun onAdLoaded(response: NativeAdResponse) {
nativeAdResponse = response
val mainImageUrl = response.imageUrl // Pass the main image URL to your app's image-loading implementation
val iconImageUrl = response.iconUrl // Pass the icon image URL to your app's image-loading implementation
findViewById<TextView>(R.id.native_ad_title).text = response.title // Render the title
findViewById<TextView>(R.id.native_ad_sponsored_by).text = response.sponsoredBy // Render the sponsor name
findViewById<TextView>(R.id.native_ad_body).text = response.description // Render the body text
response.adStarRating?.let { rating ->
findViewById<TextView>(R.id.native_ad_rating).text = "${rating.value}/${rating.scale}" // Render the rating
}
val privacyUrl = response.privacyLink // Get the privacy URL
val callToActionButton = findViewById<Button>(R.id.native_ad_call_to_action)
callToActionButton.text = response.callToAction // Render the call-to-action text
NativeAdSDK.unRegisterTracking(nativeContainer) // Stop tracking any previous ad in the container
NativeAdSDK.registerTracking(
response,
nativeContainer,
listOf(callToActionButton),
this
) // Track impressions and CTA clicks
nativeContainer.visibility = View.VISIBLE
}
override fun onAdFailed(errorCode: ResultCode, adResponseInfo: ANAdResponseInfo?) {
Log.e("NativeAdActivity", "Native ad failed to load: ${errorCode.message}")
}
override fun onAdImpression() = Unit
override fun onAdWasClicked() = Unit
override fun onAdWasClicked(clickUrl: String, fallbackURL: String) = Unit
override fun onAdWillLeaveApplication() = Unit
override fun onAdAboutToExpire() = Unit
override fun onAdExpired() = Unit
override fun onDestroy() {
NativeAdSDK.unRegisterTracking(nativeContainer) // Stop tracking and complete the viewability session
nativeAdResponse = null
super.onDestroy()
}
}
拡張ネイティブ広告アセット
標準のネイティブ広告フローに加えて、アプリはオプションで OpenRTB ネイティブまたはネイティブ アセンブリを使用して拡張アセットにアクセスできます。
openRTBAssetsに設定すると、OpenRTB ネイティブ要求は、配置に関連付けられているネイティブ アセンブリ構成よりも優先されます。
どちらのワークフローでも、アプリは、 NativeAdResponseで正規化されたアセット アクセサーを使用する代わりに、公開されたアセット オブジェクトを直接解析できます。
NativeAdResponse インスタンスを保持して、レンダリングされたコンテナーを追跡用に登録し、ネイティブ広告イベントを受信します。
| Asset | OpenRTB ネイティブ アクセス | ネイティブ アセンブリへのアクセス | 説明 |
|---|---|---|---|
| VAST ビデオ | getVastXml() |
getVastXml() |
VAST ビデオ マークアップを返します。 |
| いいね! |
getOpenRTBNative() 要求 ID 別 |
getNativeElements() および likes |
いいねの数を返します。 |
| ダウンロード |
getOpenRTBNative() 要求 ID 別 |
getNativeElements() および downloads |
ダウンロードの数を返します。 |
| Price |
getOpenRTBNative() 要求 ID 別 |
getNativeElements() および price |
製品の価格を返します。 |
| セール価格 |
getOpenRTBNative() 要求 ID 別 |
getNativeElements() および saleprice |
割引された製品価格を返します。 |
| Phone |
getOpenRTBNative() 要求 ID 別 |
getNativeElements() および phone |
広告主の電話番号を返します。 |
| アドレス |
getOpenRTBNative() 要求 ID 別 |
getNativeElements() および address |
広告主の住所を返します。 |
| 表示 URL |
getOpenRTBNative() 要求 ID 別 |
getNativeElements() および displayurl |
広告主向けの表示 URL を返します。 |
| クリック URL |
getOpenRTBNative() および link.url |
getNativeElements() および link.url |
プライマリ クリック先を返します。 |
| フォールバック URL のクリック |
getOpenRTBNative() および link.fallback |
getNativeElements() および link.fallback_url |
フォールバック クリック先を返します。 |
| カスタム拡張機能 |
getOpenRTBNative() および ext |
該当なし | デマンド パートナーによって定義された応答レベルの拡張機能データを返します。 |
OpenRTB ネイティブを使用して特定のアセットを要求する
注:
OpenRTB ネイティブは、すべてのメンバーが利用できるわけではありません。 可用性を確認するには、アカウント担当者または Microsoft Advertising サポートにお問い合わせください。
openRTBAssets には eventtrackers を含めないでください。Android SDK には、サポートされているイベント トラッカーが追加されています。
NativeAdRequest:openRTBAssets を使用して、OpenRTB ネイティブ 1.2 に従ってアプリに必要なアセットを記述します。 画像サイズ、テキストの長さ、ビデオ、カスタム アセットを指定できます。 各アセットに id を割り当てて、応答で返される値と一致させます。 また、デマンド パートナーと合意したキーと値を使用して、 ext を通じてカスタム データを追加することもできます。 使用できるフィールドと値については、 IAB OpenRTB Native Ads Specification 1.2 を参照してください。
loadAd() を呼び出す前にopenRTBAssetsを設定します。
NativeAdRequest で次の方法を使用します。
| メソッド | 説明 |
|---|---|
void setOpenRTBAssets(JSONObject openRTBAssets) |
要求されたアセットと制約を定義する OpenRTB ネイティブ 1.2 要求オブジェクトを設定します。 |
NativeAdResponse: 可能な場合は常に、SDK は標準アセットを対応するアクセサーにマップします。 完全な OpenRTB ネイティブ応答は getOpenRTBNative() からも利用でき、要求で使用される ID によって返されたアセットを見つけることができます。
NativeAdResponse で次の方法を使用します。
| メソッド | 説明 |
|---|---|
JSONObject getOpenRTBNative() |
完全な OpenRTB ネイティブ応答を返すか、使用できない場合は空の JSONObject 返します。 |
private fun loadOpenRTBNativeAd() {
nativeAdRequest = NativeAdRequest(this, "123456") // Create a request for the placement ID
nativeAdRequest.listener = this // Set the request listener
val openRTBAssets = JSONObject().apply {
put("ver", "1.2") // Set the OpenRTB Native version
put("privacy", 1) // Request privacy information
put("ext", JSONObject().put("foo", "bar")) // Add a custom request extension
put("assets", JSONArray().apply {
put(JSONObject("""{"id":1,"required":1,"title":{"len":300}}""")) // Request title
put(JSONObject("""{"id":2,"required":1,"data":{"type":2}}""")) // Request body text
put(JSONObject("""{"id":3,"required":0,"data":{"type":1}}""")) // Request sponsor name
put(JSONObject("""{"id":4,"required":0,"img":{"type":3}}""")) // Request main image
put(JSONObject("""{"id":5,"required":0,"data":{"type":12}}""")) // Request CTA text
put(JSONObject("""{"id":6,"required":0,"img":{"type":1,"hmin":50,"wmin":50}}""")) // Request icon
put(JSONObject("""{"id":7,"required":0,"data":{"type":4}}""")) // Request likes
put(JSONObject("""{"id":8,"required":0,"data":{"type":6}}""")) // Request price
put(JSONObject("""{"id":9,"required":0,"data":{"type":11}}""")) // Request display URL
})
}
nativeAdRequest.openRTBAssets = openRTBAssets // Set requested OpenRTB Native assets
nativeAdRequest.loadAd() // Load the ad
}
override fun onAdLoaded(response: NativeAdResponse) {
val openRTBNative = response.openRTBNative
val responseAssets = openRTBNative.optJSONArray("assets")
val assetsById = mutableMapOf<Int, JSONObject>()
for (index in 0 until (responseAssets?.length() ?: 0)) {
val asset = responseAssets?.optJSONObject(index)
if (asset != null) {
assetsById[asset.optInt("id")] = asset
}
}
val title = response.title // Or: assetsById[1]?.optJSONObject("title")?.optString("text")
val body = response.description // Or: assetsById[2]?.optJSONObject("data")?.optString("value")
val mainImageUrl = response.imageUrl // Or: assetsById[4]?.optJSONObject("img")?.optString("url")
val callToAction = response.callToAction // Or: assetsById[5]?.optJSONObject("data")?.optString("value")
val iconImageUrl = response.iconUrl // Or: assetsById[6]?.optJSONObject("img")?.optString("url")
val likes = assetsById[7]?.optJSONObject("data")?.optString("value") // Match request ID 7
val price = assetsById[8]?.optJSONObject("data")?.optString("value") // Match request ID 8
val displayUrl = assetsById[9]?.optJSONObject("data")?.optString("value") // Match request ID 9
val customExtension = openRTBNative.optJSONObject("ext")
val customValue = customExtension?.optString("foo") // Read a custom response extension
val link = openRTBNative.optJSONObject("link")
val clickUrl = link?.optString("url")
val clickFallbackUrl = link?.optString("fallback")
}
ネイティブ アセンブリを使用して特定のアセットを要求する
NativeAdRequest: アプリでは、ネイティブ アセンブリ固有の要求構成は必要ありません。 ネイティブ アセンブリは、Microsoft Monetize での配置用に構成され、 openRTBAssets が設定されていない場合に使用されます。 このワークフローでは、SDK は配置に関連付けられているネイティブ アセンブリの クリエイティブ アセット仕様 のみを使用します。 [ レンダラー ] タブの HTML、CSS、JAVASCRIPT は使用されません。返されたアセットをアプリでレンダリングします。 レンダラー コードは、バナー ネイティブ レンダリング ワークフローにのみ適用されます。 詳細については、「 Android のネイティブ アセンブリ レンダラー」を参照してください。 使用可能な場合は、OpenRTB ネイティブを使用することをお勧めします。 セットアップ手順については、「 ネイティブ アセンブリの構成」を参照してください。
NativeAdResponse:getNativeElements() から NativeAdResponse.NATIVE_ELEMENT_OBJECT の値を取得してJSONObjectにキャストし、各アセットをフィールド名で読み取ります。 クリエイティブによってフィールドが省略される可能性があるため、使用する前にフィールドが存在することを確認してください。
NativeAdResponse で次の方法を使用します。
| メソッド | 説明 |
|---|---|
HashMap<String, Object> getNativeElements() |
ネイティブ広告応答のすべての要素を返します。 |
val nativeElements = response.nativeElements[NativeAdResponse.NATIVE_ELEMENT_OBJECT] as? JSONObject
val title = response.title // Or: nativeElements?.optString("title")
val body = response.description // Or: nativeElements?.optString("desc")
val mainImageUrl = response.imageUrl // Or: nativeElements?.optJSONObject("main_img")?.optString("url")
val iconImageUrl = response.iconUrl // Or: nativeElements?.optJSONObject("icon")?.optString("url")
val callToAction = response.callToAction // Or: nativeElements?.optString("ctatext")
val likes = nativeElements?.optString("likes")
val price = nativeElements?.optString("price")
val link = nativeElements?.optJSONObject("link")
val clickUrl = link?.optString("url")
val clickFallbackUrl = link?.optString("fallback_url")
画像の読み込みを構成する
ネイティブ広告の応答には、メイン画像の URL とアイコンを含めることができます。 これらの URL をアプリの画像読み込み実装で使用するか、 loadAd() を呼び出す前に SDK のプリロードを有効にしてダウンロードされた Bitmap オブジェクトを受け取ります。 プリロードは既定で無効になっています。
NativeAdRequest では、次の方法を使用します。
| メソッド | 説明 |
|---|---|
void shouldLoadImage(boolean shouldLoadImage) |
SDK がメイン イメージをプリロードするかどうかを設定します。 |
void shouldLoadIcon(boolean shouldLoadIcon) |
SDK がアイコン イメージをプリロードするかどうかを設定します。 |
nativeAdRequest.shouldLoadImage(true) // Preload the main image
nativeAdRequest.shouldLoadIcon(true) // Preload the icon image
nativeAdRequest.loadAd() // Load the ad
val mainImage = response.image // Get the preloaded main image
val iconImage = response.icon // Get the preloaded icon image