---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ads.yandex.com/helpcenter/en/dev/unity/release/8-0-0-migration.md
  - https://ads.yandex.com/helpcenter/ru/dev/unity/release/8-0-0-migration.md
  - https://ads.yandex.com/helpcenter/zh/dev/unity/release/8-0-0-migration.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ads.yandex.com/helpcenter/zh/llms.txt

# 迁移至版本 8 的指南

Yandex Mobile Ads Unity 插件 8.0.0 更改了几个 API，以提升开发者体验。

## 主要变更

### 1. `AdRequest` 变更

`AdRequestConfiguration` 和 `AdRequest.Builder` 已被移除。 `adUnitId` 现已成为 `AdRequest` 构造函数的必选参数。对于 Interstitial、Rewarded 与 AppOpen 加载器，请使用 `AdRequest` 替代 `AdRequestConfiguration`。


| 类 | 状态 |
|-------|--------|
| `AdRequestConfiguration` | 已移除。 使用 `AdRequest` |
| `AdRequest.Builder` | 已移除。 使用 `AdRequest` 构造函数 |

##### 示例

###### C#

#|
|| SDK 7 | SDK 8 ||
||
```csharp
// Interstitial / Rewarded / AppOpen
AdRequestConfiguration config =
    new AdRequestConfiguration.Builder("R-M-XXXXX-YY")
        .Build();
interstitialAdLoader.LoadAd(config);

// Banner
Banner banner = new Banner(
    "R-M-XXXXX-YY",
    BannerAdSize.StickySize(320),
    AdPosition.BottomCenter);
banner.LoadAd(new AdRequest.Builder().Build());
```
|
```csharp
// Interstitial / Rewarded / AppOpen
AdRequest request = new AdRequest("R-M-XXXXX-YY");
interstitialAdLoader.LoadAd(request);

// Banner
Banner banner = new Banner(
    BannerAdSize.Sticky(320),
    AdPosition.BottomCenter);
banner.LoadAd(new AdRequest("R-M-XXXXX-YY"));
```
||
|#

### 2. 定位变更

定位字段（`Age`、`Gender`、`Location`、`ContextQuery`、`ContextTags`）已从 `AdRequestConfiguration.Builder` 和 `AdRequest.Builder` 中移除。 使用新的 `AdTargeting` 类。

| 类 | 属性 | 状态 |
|-------|----------|--------|
| `AdRequestConfiguration.Builder` | `WithAge` | 已移除。 使用 `AdTargeting(age:)` |
| `AdRequestConfiguration.Builder` | `WithGender` | 已移除。 使用 `AdTargeting(gender:)` |
| `AdRequestConfiguration.Builder` | `WithLocation` | 已移除。 使用 `AdTargeting(location:)` |
| `AdRequestConfiguration.Builder` | `WithContextQuery` | 已移除。 使用 `AdTargeting(contextQuery:)` |
| `AdRequestConfiguration.Builder` | `WithContextTags` | 已移除。 使用 `AdTargeting(contextTags:)` |
| `AdRequest.Builder` | `WithAge` | 已移除。 使用 `AdTargeting(age:)` |
| `AdRequest.Builder` | `WithGender` | 已移除。 使用 `AdTargeting(gender:)` |
| `AdRequest.Builder` | `WithLocation` | 已移除。 使用 `AdTargeting(location:)` |
| `AdRequest.Builder` | `WithContextQuery` | 已移除。 使用 `AdTargeting(contextQuery:)` |
| `AdRequest.Builder` | `WithContextTags` | 已移除。 使用 `AdTargeting(contextTags:)` |
| `AdTargeting` | — | 已添加 |

##### 示例

###### C#

#|
|| SDK 7| SDK 8 ||
||
```csharp
AdRequestConfiguration config =
    new AdRequestConfiguration.Builder("R-M-XXXXX-YY")
        .WithAge("25")
        .WithGender(Gender.MALE)
        .WithLocation(location)
        .WithContextQuery("coffee")
        .WithContextTags(new List<string> { "food", "drinks" })
        .WithParameters(parameters)
        .Build();
```
|
```csharp
AdTargeting targeting = new AdTargeting(
    age: "25",
    gender: Gender.MALE,
    location: location,
    contextQuery: "coffee",
    contextTags: new List<string> { "food", "drinks" });

AdRequest request = new AdRequest(
    "R-M-XXXXX-YY",
    targeting: targeting,
    parameters: parameters);
```
||
|#

### 3. 广告加载器变更

`OnAdLoaded` 和 `OnAdFailedToLoad` 已从 `RewardedAdLoader`、`InterstitialAdLoader` 和 `AppOpenAdLoader` 中移除。 加载结果通过 `LoadAd` 回调参数进行传递。

| 类 | 加载器 | 状态 |
|-------|--------|--------|
| `AppOpenAdLoader` | `LoadAd(request)` + `OnAdLoaded`、`OnAdFailedToLoad` | 已替换为 `LoadAd(request, onLoaded, onFailed)` |
| `InterstitialAdLoader` | `LoadAd(request)` + `OnAdLoaded`、`OnAdFailedToLoad` | 已替换为 `LoadAd(request, onLoaded, onFailed)` |
| `RewardedAdLoader` | `LoadAd(request)` + `OnAdLoaded`、`OnAdFailedToLoad` | 已替换为 `LoadAd(request, onLoaded, onFailed)` |
| `OnAdLoaded` | — | 已移除 |
| `OnAdFailedToLoad` | — | 已移除 |

##### 示例

###### C#

#|
|| SDK 7| SDK 8 ||
||
```csharp
var loader = new RewardedAdLoader();
loader.OnAdLoaded += (sender, args) => {
    _rewardedAd = args.RewardedAd;
};
loader.OnAdFailedToLoad += (sender, args) => {
    Debug.Log(args.Message);
};
loader.LoadAd(new AdRequest("R-M-XXXXX-YY"));
```
|
```csharp
var loader = new RewardedAdLoader();
loader.LoadAd(
    adRequest: new AdRequest("R-M-XXXXX-YY"),
    onLoaded: ad => { _rewardedAd = ad; },
    onFailed: args => { Debug.Log(args.Message); });
```
||
|#

同样的模式也适用于 `InterstitialAdLoader`（返回 `Interstitial`）和 `AppOpenAdLoader`（返回 `AppOpenAd`）。


#### 3.1 Async/await 支持

所有广告加载器均支持 async/await。 加载失败将抛出 `AdLoadingException`。

| 加载器 | 方法 | 状态 |
|--------|--------|--------|
| `AppOpenAdLoader` | `LoadAd(request)` | 已添加 |
| `InterstitialAdLoader` | `LoadAd(request)` | 已添加 |
| `RewardedAdLoader` | `LoadAd(request)` | 已添加 |

##### 示例

###### C#

```csharp
var loader = new RewardedAdLoader();
try
{
    _rewardedAd = await loader.LoadAd(new AdRequest("R-M-XXXXX-YY"));
}
catch (AdLoadingException e)
{
    Debug.Log(e.Message);
}
```

### 4. Banner API 变更

`blockId` 构造函数参数已从 `Banner` 中移除。 广告单元 ID 在每次加载时通过 `AdRequest` 进行传递。 `BannerAdSize` 工厂方法删除了 `Size` 后缀。

| 类 | SDK 7 | SDK 8 | 状态 |
|-------|-------|-------|--------|
|  `Banner`  | `Banner(blockId, adSize, position)` | `Banner(adSize, position)` | 已更改 |
|  `Banner`  | `LoadAd(new AdRequest.Builder().Build())` | `LoadAd(new AdRequest(blockId))` | 已更改 |
| `BannerAdSize` | `FixedSize(width, height)` | `Fixed(width, height)` | 已重命名 |
| `BannerAdSize` | `StickySize(width)` | `Sticky(width)` | 已重命名 |
| `BannerAdSize` | `InlineSize(width, maxHeight)` | `Inline(width, maxHeight)` | 已重命名 |

##### 示例

###### C#

#|
|| SDK 7| SDK 8 ||
||
```csharp
BannerAdSize sticky = BannerAdSize.StickySize(320);
Banner banner = new Banner(
    "R-M-XXXXX-YY",
    sticky,
    AdPosition.BottomCenter);
banner.LoadAd(new AdRequest.Builder().Build());
```
|
```csharp
BannerAdSize sticky = BannerAdSize.Sticky(320);
Banner banner = new Banner(
    sticky,
    AdPosition.BottomCenter);
banner.LoadAd(new AdRequest("R-M-XXXXX-YY"));
```
||
|#

### 5. 主 SDK 类重命名

`MobileAds` 已重命名为 `YandexAds`。

| SDK 7 | SDK 8 | 状态 |
|-------|-------|--------|
| `MobileAds` | `YandexAds` | 已重命名 |
| `MobileAds.SetUserConsent(consent)` | `YandexAds.SetUserConsent(consent)` | 已重命名 |
| `MobileAds.SetLocationTracking(enabled)` | `YandexAds.SetLocationTracking(enabled)` | 已重命名 |
| `MobileAds.SetAgeRestricted(restricted)` | `YandexAds.SetAgeRestricted(restricted)` | 已重命名 |
| `MobileAds.ShowDebugPanel()` | `YandexAds.ShowDebugPanel()` | 已重命名 |

##### 示例

###### C#

#|
|| SDK 7| SDK 8 ||
||
```csharp
MobileAds.SetUserConsent(true);
MobileAds.SetLocationTracking(true);
MobileAds.SetAgeRestricted(false);
```
|
```csharp
YandexAds.SetUserConsent(true);
YandexAds.SetLocationTracking(true);
YandexAds.SetAgeRestricted(false);
```
||
|#

### 6. `AdInfo` 变更

`AdSize` 已从 `AdInfo` 中移除。 新属性：`ExtraData`、`PartnerText`、`Creatives`。

| 类 | SDK 7 | SDK 8 | 状态 |
|-------|-------|-------|--------|
| `AdInfo` | `AdUnitId` | `AdUnitId` | 未更改 |
| `AdInfo` | `AdSize` | — | 已移除 |
| `AdInfo` | — | `ExtraData` | 已添加 |
| `AdInfo` | — | `PartnerText` | 已添加（仅 ADFOX） |
| `AdInfo` | — | `Creatives` | 已添加 |

##### 示例

###### C#

#|
|| SDK 7| SDK 8 ||
||
```csharp
string adUnitId = adInfo.AdUnitId;
AdSize adSize = adInfo.AdSize;
```
|
```csharp
string adUnitId = adInfo.AdUnitId;
string extraData = adInfo.ExtraData;
string partnerText = adInfo.PartnerText; // 仅 ADFOX

if (adInfo.Creatives != null)
{
    foreach (Creative creative in adInfo.Creatives)
    {
        string creativeId = creative.CreativeId;
        string campaignId = creative.CampaignId;
        string placeId    = creative.PlaceId;
    }
}
```
||
|#


### 7. `GetInfo()` 可用性

`GetInfo()` 可用于所有广告类型，包括 `AppOpenAd` 和 `Banner` 。

| 广告类型 | SDK 7 | SDK 8 | 状态 |
|---------|-------|-------|--------|
| `Interstitial.GetInfo()` | ✓ | ✓ | 未更改 |
| `RewardedAd.GetInfo()` | ✓ | ✓ | 未更改 |
| `AppOpenAd.GetInfo()` | — | ✓ | 已添加 |
| `Banner.GetInfo()` | — | ✓ | 已添加 |

##### 示例

###### C#

```csharp
// SDK 8：GetInfo() 适用于所有广告类型
AdInfo adInfo = banner.GetInfo();
if (adInfo != null)
{
    Debug.Log($"AdUnitId: {adInfo.AdUnitId}");
}
```