---
metadata:
- name: generator
content: Diplodoc Platform v5.52.0
alternate:
- https://ads.yandex.com/helpcenter/en/easy/integration/android/formats/native.md
- https://ads.yandex.com/helpcenter/ru/easy/integration/android/formats/native.md
- https://ads.yandex.com/helpcenter/zh/easy/integration/android/formats/native.md
- href: zh/easy/integration/android/formats/native.md
type: text/markdown
title: Markdown version
- href: ../llms.txt
type: text/markdown
title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt
# 原生广告
原生广告是一种可由应用端自定义广告外观的广告格式。使用此功能可以调整广告的视觉风格和版位，使其与您的应用设计相匹配。
{% note info %}
[演示项目](https://ads.yandex.com/helpcenter/zh/easy/integration/android/testing.md#demo) 中提供了展示所有格式类型运作原理的示例。
{% endnote %}
#|
||
**实体**
|
**描述**
||
||
`onAdFailedToLoad`
|
如果 `onAdFailedToLoad()` 返回错误，请勿尝试**使用相同方法**再次加载新广告。
||
||
`NativeAdRequestConfiguration`
|
在请求参数中，您可以指定广告单元编号（`RM-id`）、图片加载方式、年龄、性别，以及其他可以使展示的广告更具相关性的数据。如需详细了解，请参阅[广告定位](https://ads.yandex.com/helpcenter/zh/easy/integration/android/advanced-settings/targeting.md)。
||
||
`adUnitId`
|
使用：
- **Development mode**，用于配合[演示广告单元](https://ads.yandex.com/helpcenter/zh/easy/integration/android/testing.md#blocks) 使用。
- **Production mode**，用于配合 `R-M-XXXXXX-Y` 使用（实际 ID 请在 Yandex Advertising Network 界面查询）。`R-M-XXXXXX-Y` 是您实际广告单元 ID 的模板，将用于接收各种广告创意。
||
|#
## 创建原生广告示例
定义 `CustomNative` 类并创建 `NativeAdView.xml`：
{% list tabs %}
- Kotlin
```kotlin
class CustomNativeAdActivity : AppCompatActivity(), NativeAdEventListener {
private val nativeAdView get() = binding.nativeAd.root
private val additionalContainer get() = binding.additionalContainer
private val adUnitId = "demo-native-app-yandex" // 使用 R-M-XXXXXX-Y 或演示广告单元（请参阅下方说明）
private var nativeAdLoader: NativeAdLoader? = null
private lateinit var binding: ActivityCustomNativeAdBinding
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityCustomNativeAdBinding.inflate(layoutInflater)
binding.btnShowBanner.setOnClickListener {
loadNative()
}
setContentView(binding.root)
}
private fun loadNative() {
createNative()
additionalContainer.removeAllViews()
nativeAdView.isVisible = false
nativeAdLoader?.loadAd(buildAdRequestConfiguration())
}
private fun createNative() {
nativeAdLoader = NativeAdLoader(this).apply {
setNativeAdLoadListener(object : NativeAdLoadListener {
override fun onAdLoaded(ad: NativeAd) {
bindNative(ad)
}
override fun onAdFailedToLoad(error: AdRequestError) {}
})
}
}
private fun buildAdRequestConfiguration(): NativeAdRequestConfiguration {
return NativeAdRequestConfiguration
.Builder(adUnitId)
.setShouldLoadImagesAutomatically(true)
.build()
}
private fun bindNative(nativeAd: NativeAd) {
val nativeAdViewBinder = binding.nativeAd.run {
NativeAdViewBinder.Builder(nativeAdView)
.setAgeView(age)
.setBodyView(body)
.setCallToActionView(callToAction)
.setDomainView(domain)
.setFaviconView(favicon)
.setFeedbackView(feedback)
.setIconView(icon)
.setMediaView(media)
.setPriceView(price)
.setRatingView(rating)
.setReviewCountView(reviewCount)
.setSponsoredView(sponsored)
.setTitleView(title)
.setWarningView(warning)
.build()
}
try {
nativeAd.bindNativeAd(nativeAdViewBinder)
nativeAd.info?.let { processAdditionalText(it) }
nativeAd.setNativeAdEventListener(this@CustomNativeAdActivity)
nativeAdView.isVisible = true
} catch (exception: NativeAdException) {
println("Error binding native ad: ${exception.message}")
}
}
private fun processAdditionalText(rawJson: String) {
try {
val jsonObject = JSONObject(rawJson)
val contentJSONArray = jsonObject.getJSONArray("content")
repeat(contentJSONArray.length()) { index ->
val elementName = contentJSONArray.getString(index)
val elementConfiguration = jsonObject.getJSONObject(elementName)
when (elementName) {
"text" -> addTextToLayout(elementConfiguration, index)
"button" -> addButtonToLayout(elementConfiguration, index)
}
}
} catch (e: JSONException) {
println("Error processing additional text: ${e.message}")
}
}
private fun addTextToLayout(textConfiguration: JSONObject, index: Int) {
val textView = TextView(this).apply {
setPadding(16)
text = textConfiguration.getString("value")
}
additionalContainer.addView(textView, index)
}
private fun addButtonToLayout(buttonConfiguration: JSONObject, index: Int) {
val buttonView = Button(this).apply {
setPadding(16)
text = buttonConfiguration.getString("label")
val colorHex = buttonConfiguration.getString("backgroundColor")
setBackgroundColor(Color.parseColor(colorHex))
setOnClickListener {
val link = buttonConfiguration.getString("link")
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(link))
startActivity(intent)
}
}
additionalContainer.addView(buttonView, index)
}
override fun onDestroy() {
nativeAdLoader?.setNativeAdLoadListener(null)
nativeAdLoader = null
super.onDestroy()
}
override fun onAdClicked() {}
override fun onImpression(impressionData: ImpressionData?) {}
override fun onLeftApplication() {}
override fun onReturnedToApplication() {}
}
```
- Java
```java
public class CustomNativeAdActivity extends AppCompatActivity implements NativeAdEventListener {
private ActivityCustomNativeAdBinding binding;
private NativeAdLoader nativeAdLoader;
private NativeAdViewBinder nativeAdViewBinder;
private final String adUnitId = "demo-native-app-yandex"; // 使用 R-M-XXXXXX-Y 或演示广告单元（请参阅下方说明）
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
binding = ActivityCustomNativeAdBinding.inflate(getLayoutInflater());
setContentView(binding.getRoot());
binding.btnShowBanner.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
loadNative();
}
});
}
private void loadNative() {
createNative();
binding.additionalContainer.removeAllViews();
binding.nativeAd.getRoot().setVisibility(View.GONE);
if (nativeAdLoader != null) {
nativeAdLoader.loadAd(buildAdRequestConfiguration());
}
}
private void createNative() {
nativeAdLoader = new NativeAdLoader(this);
nativeAdLoader.setNativeAdLoadListener(new NativeAdLoadListener() {
@Override
public void onAdLoaded(NativeAd ad) {
bindNative(ad);
}
@Override
public void onAdFailedToLoad(AdRequestError error) {}
});
}
private NativeAdRequestConfiguration buildAdRequestConfiguration() {
return new NativeAdRequestConfiguration.Builder(adUnitId)
.setShouldLoadImagesAutomatically(true)
.build();
}
private void bindNative(NativeAd nativeAd) {
NativeAdLayoutBinding adBinding = binding.nativeAd;
// 手动创建绑定（或 ViewBinding 自动生成时）
nativeAdViewBinder = new NativeAdViewBinder.Builder(adBinding.getRoot())
.setAgeView(adBinding.age)
.setBodyView(adBinding.body)
.setCallToActionView(adBinding.callToAction)
.setDomainView(adBinding.domain)
.setFaviconView(adBinding.favicon)
.setFeedbackView(adBinding.feedback)
.setIconView(adBinding.icon)
.setMediaView(adBinding.media)
.setPriceView(adBinding.price)
.setRatingView(adBinding.rating)
.setReviewCountView(adBinding.reviewCount)
.setSponsoredView(adBinding.sponsored)
.setTitleView(adBinding.title)
.setWarningView(adBinding.warning)
.build();
try {
nativeAd.bindNativeAd(nativeAdViewBinder);
String infoJson = nativeAd.getInfo();
if (infoJson != null) {
processAdditionalText(infoJson);
}
nativeAd.setNativeAdEventListener(this);
adBinding.getRoot().setVisibility(View.VISIBLE);
} catch (NativeAdException exception) {
System.out.println("Error binding native ad: " + exception.getMessage());
}
}
private void processAdditionalText(String rawJson) {
try {
JSONObject jsonObject = new JSONObject(rawJson);
JSONArray contentJSONArray = jsonObject.getJSONArray("content");
for (int i = 0; i < contentJSONArray.length(); ++i) {
String elementName = contentJSONArray.getString(i);
JSONObject elementConfiguration = jsonObject.getJSONObject(elementName);
switch (elementName) {
case "text":
addTextToLayout(elementConfiguration, i);
break;
case "button":
addButtonToLayout(elementConfiguration, i);
break;
}
}
} catch (JSONException e) {
System.out.println("Error processing additional text: " + e.getMessage());
}
}
private void addTextToLayout(JSONObject textConfiguration, int index) {
TextView textView = new TextView(this);
textView.setPadding(16, 16, 16, 16);
try {
textView.setText(textConfiguration.getString("value"));
} catch (JSONException ignored) { }
binding.additionalContainer.addView(textView, index);
}
private void addButtonToLayout(final JSONObject buttonConfiguration, int index) {
Button buttonView = new Button(this);
buttonView.setPadding(16, 16, 16, 16);
try {
buttonView.setText(buttonConfiguration.getString("label"));
String colorHex = buttonConfiguration.getString("backgroundColor");
buttonView.setBackgroundColor(Color.parseColor(colorHex));
buttonView.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
try {
String link = buttonConfiguration.getString("link");
Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(link));
startActivity(intent);
} catch (JSONException ignored) { }
}
});
} catch (JSONException ignored) { }
binding.additionalContainer.addView(buttonView, index);
}
@Override
protected void onDestroy() {
if (nativeAdLoader != null) {
nativeAdLoader.setNativeAdLoadListener(null);
nativeAdLoader = null;
}
super.onDestroy();
}
@Override
public void onAdClicked() {}
@Override
public void onImpression(@Nullable ImpressionData impressionData) {}
@Override
public void onLeftApplication() {}
@Override
public void onReturnedToApplication() {}
}
```
- activity_custom_native_ad.xml
```xml
```
- native_ad_view.xml
```xml
```
{% endlist %}
## 检查集成
创建并运行您的项目。您可以通过在 **Logcat** 中搜索 `YandexAds` 关键字来检查集成是否成功：
```
[Integration] Ad type native was integrated successfully
```