---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ads.yandex.com/helpcenter/en/easy/integration/unity/formats/app-open-ads.md
  - https://ads.yandex.com/helpcenter/ru/easy/integration/unity/formats/app-open-ads.md
  - https://ads.yandex.com/helpcenter/zh/easy/integration/unity/formats/app-open-ads.md
  - href: zh/easy/integration/unity/formats/app-open-ads.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

# 开屏广告

<!-- source: zh/easy/_includes/sdk-guide.md -->
开屏广告是一种特殊的广告格式，用于通过应用加载屏幕变现。

{% note alert %}

该广告格式仅支持**竖屏显示**。若使用横屏模式，广告将无法正常展示。

{% endnote %}
<!-- endsource: zh/easy/_includes/sdk-guide.md -->

<!-- source: zh/easy/_includes/notes-unity-easy-guide.md -->
{% note info %}

[演示项目](https://ads.yandex.com/helpcenter/zh/easy/integration/unity/testing.md#demo)中提供了展示所有格式类型运作原理的示例。

{% endnote %}
<!-- endsource: zh/easy/_includes/notes-unity-easy-guide.md -->


#|
||

**实体**

|

**描述**

||
||

`adUnitId`

|

用途：

- **开发模式**，用于配合[演示广告单元](https://ads.yandex.com/helpcenter/zh/easy/integration/unity/testing.md#blocks)使用。

- **生产模式**，用于配合 `R-M-XXXXXX-Y` 使用（实际 ID 请在 Yandex Advertising Network 界面查询）。`R-M-XXXXXX-Y` 是您实际广告单元 ID 的模板，将用于接收各种广告创意。

||
|#

## 开屏广告创建示例

```C#
using UnityEngine;
using UnityEngine.Events;
using YandexMobileAds;
using YandexMobileAds.Base;
using System.Collections.Generic;
using System;

[AddComponentMenu("Yandex Ads/App Open Ad Component")]
public class AppOpenAdComponent : MonoBehaviour
{
    [Header("Ad Settings")]
    public string adName = "Default App Open Ad";

    [Header("Ad Unit IDs")]
    [Tooltip("Ad Unit ID for Android")]
    public string adUnitIdAndroid = "demo-appopenad-yandex";

    [Tooltip("Ad Unit ID for iOS")]
    public string adUnitIdiOS = "demo-appopenad-yandex";

    [Header("Configuration")]
    public bool autoLoading = true;
    public bool showAfterLoading = true;
    public bool showAppOpenAdOnce = true;

    private AppOpenAd appOpenAd;
    private AppOpenAdLoader appOpenAdLoader;
    private bool isColdStartAdShown = false;

    [System.Serializable]
    public class AdEventWithAd : UnityEvent<AppOpenAd> { }

    [System.Serializable]
    public class AppStateChangedEvent : UnityEvent<AppStateChangedEventArgs, AppOpenAd> { }

    [Header("Load Callbacks")]
    public AdEventWithAd OnAdLoaded;
    public UnityEvent<string> OnAdFailedToLoad;

    [Header("Interaction Callbacks")]
    public AdEventWithAd OnAdShown;
    public AdEventWithAd OnAdDismissed;
    public AdEventWithAd OnAdClicked;
    public UnityEvent<string> OnAdFailedToShow;
    public UnityEvent<string> OnImpression;
    public AppStateChangedEvent OnAppStateChange;

    private string CurrentAdUnitId
    {
        get
        {
#if UNITY_IOS
            return adUnitIdiOS;
#elif UNITY_ANDROID
            return adUnitIdAndroid;
#else
            Debug.LogWarning("Unsupported platform for Yandex Ads. Using Android Ad Unit ID by default.");
            return adUnitIdAndroid;
#endif
        }
    }

    private void Start()
    {
        if (!string.IsNullOrEmpty(CurrentAdUnitId))
        {
            AppStateObserver.OnAppStateChanged += HandleAppStateChanged;
            SetupLoader();
            if (autoLoading)
            {
                Load();
            }
            DontDestroyOnLoad(gameObject);
        }
        else
        {
            Debug.Log("App open ad: Ad Unit ID is missing.");
        }
    }

    private void SetupLoader()
    {
        appOpenAdLoader = new AppOpenAdLoader();
        appOpenAdLoader.OnAdLoaded += HandleAdLoaded;
        appOpenAdLoader.OnAdFailedToLoad += HandleAdFailedToLoad;
    }

    private void ConfigureAd()
    {
        double lat = 60.0, lon = 30.0;

        // 构建位置对象
        Location location = new Location.Builder()
            .SetLatitude(lat)
            .SetLongitude(lon)
            .Build();

        AdRequestConfiguration adRequestConfiguration = new AdRequestConfiguration.Builder(CurrentAdUnitId)
                .WithAge("25")
                .WithGender("male") // 或 "female"、"other"
                .WithContextTags(new List<string>() { "games", "unity", "test" })
                .WithContextQuery("user_search_query") // 搜索查询字符串
                .WithLocation(location)
                .WithParameters(new Dictionary<string, string> {
                        { "custom1", "value1" },
                        { "custom2", "value2" }
                }).Build();
        try
        {
            appOpenAdLoader.LoadAd(adRequestConfiguration);
        }
        catch (Exception ex)
        {
            OnAdFailedToLoad?.Invoke($"Configuration failed: {ex.Message}");
        }
    }

    public void Load()
    {
        var isBlcokedForLoad = showAppOpenAdOnce && isColdStartAdShown;
        if (!isBlcokedForLoad)
        {
            ConfigureAd();
        }
    }

    public void Show()
    {
        if (appOpenAd != null)
        {

            if (showAppOpenAdOnce)
            {
                if (!isColdStartAdShown)
                {
                    appOpenAd.Show();
                    isColdStartAdShown = true;
                }
            }
            else
            {
                appOpenAd.Show();
            }
        }
        else
        {
            Debug.Log("Failed to show ad. Ad object not loaded");
        }
    }

    public void OnDestroy()
    {
        AppStateObserver.OnAppStateChanged -= HandleAppStateChanged;
        if (appOpenAd != null)
        {
            appOpenAd.OnAdShown -= HandleAdShown;
            appOpenAd.OnAdDismissed -= HandleAdDismissed;
            appOpenAd.OnAdClicked -= HandleAdClicked;
            appOpenAd.OnAdFailedToShow -= HandleAdFailedToShow;
            appOpenAd.OnAdImpression -= HandleImpression;
            appOpenAd.Destroy();
            appOpenAd = null;
        }
    }

    #region Event Handlers

    private void HandleAdLoaded(object sender, AppOpenAdLoadedEventArgs args)
    {
        appOpenAd = args.AppOpenAd;
        appOpenAd.OnAdShown += HandleAdShown;
        appOpenAd.OnAdDismissed += HandleAdDismissed;
        appOpenAd.OnAdClicked += HandleAdClicked;
        appOpenAd.OnAdFailedToShow += HandleAdFailedToShow;
        appOpenAd.OnAdImpression += HandleImpression;
        OnAdLoaded?.Invoke(appOpenAd);
        if (showAfterLoading)
        {
            if (showAppOpenAdOnce)
            {
                if (!isColdStartAdShown)
                {
                    appOpenAd.Show();
                    isColdStartAdShown = true;
                }
            }
            else
            {
                appOpenAd.Show();
            }
        }
    }

    private void HandleAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) => OnAdFailedToLoad?.Invoke(args.Message);

    private void HandleAdShown(object sender, EventArgs args) => OnAdShown?.Invoke(appOpenAd);

    private void HandleAdDismissed(object sender, EventArgs args) => OnAdDismissed?.Invoke(appOpenAd);

    private void HandleAdClicked(object sender, EventArgs args) => OnAdClicked?.Invoke(appOpenAd);

    private void HandleAdFailedToShow(object sender, AdFailureEventArgs args) => OnAdFailedToShow?.Invoke(args.Message);

    private void HandleImpression(object sender, ImpressionData impressionData) => OnImpression?.Invoke(impressionData?.rawData ?? string.Empty);

    private void HandleAppStateChanged(object sender, AppStateChangedEventArgs args) => OnAppStateChange?.Invoke(args, appOpenAd);

    #endregion
}
```

## 检查集成

<!-- source: zh/easy/_includes/notes-unity-easy-guide.md -->
创建并运行您的项目。您可以通过在 **Android Studio** 的 **Logcat** 中搜索 `YandexAds` 关键字来检查集成是否成功：
<!-- endsource: zh/easy/_includes/notes-unity-easy-guide.md -->

```
[Integration] Ad type App Open was integrated successfully
```