为 iOS 构构建自定义适配器

通过创建底部适配器类和广告单元类、初始化网络 SDK 并实现广告单元逻辑，在 iOS 上为网络开发自定义适配器。

阅读时间1 分钟

最后更新于 3 天前

本文档介绍构建自定义适配器的步骤，并向发布者提供将网络与 Unity LevelPlay 集成所需的资源。

先决条件

填写自定义适配器注册表
确保您拥有以下可用信息：
- 适配器类名称
- 网络配置密钥
在此处下载最新的 LevelPlay SDK

还应考虑以下最佳实践：

确保在代码中处理主线程要求
确保添加代码保护和异常处理以保护应用程序免受意外故障的影响。

为网络创建适配器

您的网络适配器将管理网络广告服务逻辑，并允许发布商将网络广告服务作为其 Unity LevelPlay 配置的一部分进行显示。

作为此过程的一部分，您需要创建一个适配器类（称为 BaseAdapter）以及一个用于打算支持的每个广告单元的附加类。

BaseAdapter 将支持您的网络管理，包括网络初始化过程，并允许您为所有广告单位定义在整个会话中可用的变量和常量。

广告单元类将管理用于加载、展示和管理广告的广告单元逻辑，并将根据瀑布流中的每个广告展示进行实例化。

创建网络底部适配器

要实现网络适配器，请创建一个新类并导入 ironSource ISBaseNetworkAdapter 类。

使用您在创建适配器时从网络注册确认电子邮件收到的底部适配器名称。


#import "IronSource/IronSource.h"@interface IS<YourNetworkName>CustomAdapter：ISBaseNetworkAdapter


@objc(IS<YourNetworkName> CustomAdapter)public 类 IS<YourNetworkName>CustomAdapter:ISBaseNetworkAdapter {   ...}

初始化网络 SDK

Unity LevelPlay 将在聚合中的任何初始化过程中调用底部适配器的 init 方法。因此，可以多次调用此方法。

作为 init 实现的一部分，请务必在时间成功 (onInitSuccess) 和/或失败 (onInitFailed) 时调用 NetworkInitializationListener 中定义的初始化回调。

adData 参数将包含发布者在 Unity LevelPlay 平台中提供的配置数据。在此处了解有关 ISAdData 类的更多信息。


(void)init：(ISAdData *)adDatadelegate:(id<ISNetworkInitializationDelegate>)delegate {    ...   // 处理错误    if (error- handling) {       [delegate onInitDidFailWithErrorCode:ISAdapterErrorMissingParams                               errorMessage:error];    }    // 初始化成功    [delegate onInitDidSucceed]; }


公共覆盖 func `init` (_ adData:ISAdData，委托：ISNetworkInitializationDelegate) {   ...   // 处理错误    if (error- handling) {       delegate.onInitDidFailWithErrorCode(ISAdapterErrors.missingParams.rawValue, errorMessage:"未能初始化 SDK")      返回   }    // 初始化成功    delegate.onInitDidSucceed()   返回        }

提供 SDK 和适配器版本

此信息将指示发布者的 app 上当前实现了哪些 SDK 和适配器版本。在实现 getNetworkSDKVersion 时，我们建议使用方法而不是硬编码值，以便在适配器更新和 SDK 支持方面实现更大的灵活性。


- (NSString *) networkSDKVersion { }   return [ALSdk version];}- (NSString *) adapterVersion { }   return kAdapterVersion;}


public 覆盖 func networkSDKVersion() -> 字符串 {   return yourNetworkSDKVersion()}public 覆盖 func adapterVersion() -> 字符串 {   return self.customAdapterVersion;}

添加对插页式广告单元的支持

创建插页式广告单元类

创建一个用于管理插页式广告单元的类。导入 ironsource ISBaseAdAdapter，并确保向主适配器文件添加相关委托。每当发布者通过加载方法在app程序中触发新的插页式广告时，都会激活类。

使用您在注册过程中从 ironSource 收到的插页类名称。


#import "IronSource/IronSource.h"@interface IS<YourNetworkName>CustomInterstitial：ISBaseInterstitial


@objc(IS<YourNetworkName> CustomInterstitial)public 类 IS<YourNetworkName>CustomInterstitial：ISBaseInterstitial {   ...}

请求插页式广告

覆盖 loadAdWithAdData 方法，允许发布者从您的网络请求插页广告服务。ISAdData 允许您访问发布者输入并接收此过程所需的广告标识符。

确保实现 ISInterstitialAdDelegate 回调，以便成功加载广告 (adDidLoad) 和任何类型的失败 (adDidFailToLoadWithErrorType)。如果监听器回调在预定义时间后未触发，则冥想将因超时而停止加载过程，并且网络将无法提供广告。


- (void)loadAdWithAdData：(nonnull ISAdData *)adData               delegate:(nonnull id<ISInterstitialAdDelegate>)delegate {   // Load your ad }


public 覆盖 func loadAd(with adData:ISAdData，委托：ISInterstitialAdDelegate) {   // Load your ad}

检查广告是否可用

覆盖 isAdAvailableWithAdData 方法，允许发布者在尝试向用户展示每个广告之前检查其准备情况。如果成功加载广告，则该方方法返回 YES，如果当前未加载广告，则返回 NO。为此，可使用网络的 is-ad-available 指示（如果存在），或通过手动管理广告状态（作为 loadAdWithAdData 和 showAdWithViewController 方法的一部分）。


- (BOOL)isAdAvailableWithAdData:(nonnull ISAdData *)adData {   return _renderedAd != nil;}


public 覆盖 func isAdAvailable（使用 adData：ISAdData) -> Bool {   ...   return false}

显示插页式广告

成功加载广告后，发布者应该能够显示该广告。在验证 isAdAvailableWithAdData 为 true 后，可以覆盖 showAdWithViewController 方法，从而为发布者提供更好的体验。此方法收到的部分信息是 ISAdData。使用此对象时，将允许您展示相关广告。如果无法执行显示，则应返回 adDidFailToShowWithErrorCode 回调。


- (void)showAdWithViewController：(nonnull UIViewController *)viewController                        adData：(nonnull ISAdData *)adData                        delegate:(nonnull id<ISInterstitialAdDelegate>)delegate {   // 检查是否可以显示广告   if (CannotShowsAd) {      [delegate adDidFailToShowWithErrorCode:ISAdapterErrorInternal                                 errorMessage:nil];      return;   }   // 显示广告    [_ad showAd:_renderedAd];}


public 覆盖 func showAd(with viewController:UIViewController、adData：ISAdData，委托：ISInterstitialAdDelegate) {   //保存委托   self.adDelegate = delegate         // verify you have an ad to show for this configuration   if isAdReady(withInstanceData: instanceData)) else {      // return show failed callback      delegate.adDidFailToShowWithErrorCode(ISAdapterErrors.internal.rawValue, errorMessage："ad is not ready to show for the current instanceData")      返回   }   // show your network interstitial ad   showInterstitialAd(withInstanceData: instanceData, adDelegate: self)}

报告 ISInterstitialAdDelegate 回调

确保根据网络的功能覆盖 ISInterstitialAdDelegate 回调。正确报告委托将确保 Unity LevelPlay 的最佳实践流程，并启用网络性能数据在 IronSource 平台中正确反映。

强制回调


// 指示插页式广告已成功加载 - (void)adDidLoad;// The interstitial ad failed to load. Use ironSource ErrorTypes (No Fill / Other)- (void)adDidFailToLoadWithErrorType:(ISAdapterErrorType)errorType                           errorCode：(NSInteger)errorCode                        errorMessage：(NSString*)errorMessage;// The interstitial ad was displayed successfully to the user.这表示展示量。- (void)adDidOpen;// User closed the interstitial ad- (void)adDidClose;// The ad could not be displayed- (void)adDidFailToShowWithErrorCode:(NSInteger)errorCode                        errorMessage：(NSString*)errorMessage;


// 指示插页式广告已成功加载 public func adDidLoad()// The interstitial ad failed to load. Use ironSource ErrorTypes (No Fill / Other)public func adDidFailToLoadWith(_ errorType:ISAdapterErrorType、errorCode：Int, errorMessage：字符串！)// The interstitial ad was displayed successfully to the user.这表示展示量。public func adDidOpen()// User closed the interstitial adpublic func adDidClose()// The ad could not be displayedpublic func adDidFailToShowWithErrorCode(_ errorCode:Int, errorMessage：字符串！)

可选回调


// 实现如果除了广告打开（展示）之外，广告网络报告还显示成功指示 - (void)adDidShowSucceed;// Indicates the ad was clicked- (void)adDidClick;


// 实现如果除了广告打开（展示）之外，广告网络报告还显示成功指示 public func adDidShowSucceed()// Indicates the ad was clickedpublic func adDidClick()

如何从底部适配器获取数据（可选）

如果您的底部适配器通过会话管理与广告单位相关的状态或参数，请使用 getNetworkAdapter API。这包括任何定义为底部适配器一部分的对象，这些对象应在广告单元 API 中使用。


// example of data retrieved from your network level adapterIS<yourNetworkName>CustomAdapter *sampleNetworkAdapter = nil;id<ISAdapterBaseProtocol> adapter = [self getNetworkAdapter];if ([adapter isKindOfClass:[IS<yourNetworkName>CustomAdapter class]]) {   sampleNetworkAdapter = (IS<yourNetworkName>CustomAdapter*) adapter;}

添加对奖励视频广告单元的支持

创建奖励视频广告单元类

使用您在注册过程中从 ironSource 收到的奖励视频类名称。


#import "IronSource/IronSource.h"@interface IS<YourNetworkName>CustomRewardedVideo：ISBaseRewardedVideo


@objc(IS<YourNetworkName>CustomRewardedVideo)public 类 IS<YourNetworkName>CustomRewardedVideo：ISBaseRewardedVideo {   ...}

请求奖励视频广告

覆盖 loadAdWithAdData 方法，允许发布者从您的网络请求插页广告服务。ISAdData 允许您访问发布者输入并接收此过程所需的广告标识符。

确保实现 ISRewardedVideoAdDelegate 回调，以便成功加载广告 (adDidLoad) 和任何类型的失败 (adDidFailToLoadWithErrorType)。如果监听器回调在预定义时间后未触发，则冥想将因超时而停止加载过程，并且网络将无法提供广告。


- (void)loadAdWithAdData：(nonnull ISAdData *)adData               delegate:(nonnull id<ISRewardedVideoAdDelegate>)delegate {   // Load your ad}


public 覆盖 func loadAd(with adData:ISAdData，委托：ISRewardedVideoAdDelegate) {   // Load your ad}

检查广告是否可用


- (BOOL)isAdAvailableWithAdData:(nonnull ISAdData *)adData {   ...   return _renderedAd != nil;}


public 覆盖 func isAdAvailable（使用 adData：ISAdData) -> Bool {   ...   return false}

显示奖励视频广告


- (void)showAdWithViewController：(nonnull UIViewController *)viewController                        adData：(nonnull ISAdData *)adData                        delegate:(nonnull id<ISRewardedVideoAdDelegate>)delegate {   // 检查是否可以显示广告 if ( cannotShowsAd) {      [delegate adDidFailToShowWithErrorCode:ISAdapterErrorInternal                              errorMessage:nil];         return;   }   // show ad   [_ad showAd:_renderedAd];}


public 覆盖 func showAd(with viewController:UIViewController、adData：ISAdData，委托：ISRewardedVideoAdDelegate) {   //保存委托   self.adDelegate = delegate         // verify you have an ad to show for this configuration   if isAdReady(withInstanceData: instanceData)) else {      // return show failed callback      delegate.adDidFailToShowWithErrorCode(ISAdapterErrors.internal.rawValue, errorMessage："ad is not ready to show for the current instanceData")      返回   }   // show rewarded video ad   showRewardedVideoAd(withInstanceData: instanceData, adDelegate: self)}

报告 ISRewardedVideoAdDelegate 回调

确保根据网络的功能覆盖 ISRewardedVideoAdDelegate 回调。正确报告委托将确保 Unity LevelPlay 聚合的最佳实践流程，并启用网络性能数据在 IronSource 平台中正确反映。

强制回调


// 指示奖励视频广告已成功加载 - (void)adDidLoad;// The rewarded video ad failed to load. Use ironSource ErrorTypes (No Fill / Other)- (void)adDidFailToLoadWithErrorType:(ISAdapterErrorType)errorType                           errorCode：(NSInteger)errorCode                        errorMessage：(NSString*)errorMessage;// The rewarded video ad was displayed successfully to the user.这表示展示量。- (void)adDidOpen;// User closed the rewarded video ad- (void)adDidClose;// The ad could not be displayed- (void)adDidFailToShowWithErrorCode:(NSInteger)errorCode                        errorMessage：(NSString*)errorMessage;// User clicked the rewarded video ad- (void)adDidClick;// User received a reward after watching the ad- (void)adRewarded;


// 指示奖励视频广告已成功加载 public func adDidLoad()// The rewarded video ad failed to load. Use ironSource ErrorTypes (No Fill / Other)public func adDidFailToLoadWith(_ errorType:ISAdapterErrorType、errorCode：Int, errorMessage：字符串！)// The rewarded video ad was displayed successfully to the user.这表示展示量。public func adDidOpen()// User closed the rewarded video adpublic func adDidClose()// The ad could not be displayedpublic func adDidFailToShowWithErrorCode(_ errorCode:Int, errorMessage：字符串！)// User clicked the rewarded video adpublic func adDidClick()// User received a reward after watching the adpublic func adRewarded()

可选回调


// 指示视频广告已启动 - (void)adDidStart;// Indicates the video ad ended- (void)adDidEnd// indicates that ad is displayed on foreground-（无效）adDidBecomeVisible// Implement if in addition to ad-open (impression), your ad network reports also show success indication-（无效）adDidShowSucceed


// 指示视频广告已启动 public func adDidStart()// Indicates the video ad endedpublic func adDidEnd()// Indicates that ad is displayed on foregroundpublic func adDidBecomeVisible()// Implement if in addition to ad-open (impression), your ad network reports also show success indicationpublic func adDidShowSucceed()

如何从底部适配器获取数据（可选）


// example of data retrieved from your network level adapterIS<yourNetworkName>CustomAdapter *sampleNetworkAdapter = nil;id<ISAdapterBaseProtocol> adapter = [self getNetworkAdapter];if ([adapter isKindOfClass:[IS<yourNetworkName>CustomAdapter class]]) {   sampleNetworkAdapter = (IS<yourNetworkName>CustomAdapter*) adapter;}

添加对横幅广告单元的支持

步骤 1.创建横幅广告单元类

创建一个用于管理横幅广告单元的类。每当发布者通过加载方法在app程序中触发新的横幅广告时，都会激活类。

使用您在注册过程中从 ironSource 收到的横幅类名称。


#import "IronSource/IronSource.h"@interface IS<YourNetworkName>CustomBanner：ISBaseBanner


@objc(IS<YourNetworkName> CustomBanner)public 类 IS<YourNetworkName>CustomBanner：ISBaseBanner {}

横幅大小

请参阅下表以了解我们支持的横幅大小的详细信息。自定义网络可能支持这些大小的任意组合。横幅大小将作为参数接收，作为 loadAdWithAdData API 的一部分。

当收到的横幅大小为 **SMART 时，**请确保根据设备屏幕大小将大小更改为 BANNER 或 LEADERBOARD（请参阅以下说明）。

ISBannerSize	描述	以点为单位的尺寸 (WxH)
ISBannerSize_BANNER	标准横幅	320 x 50
ISBannerSize_LARGE	大横幅	320 x 90
ISBannerSize_RECTANGLE	中等矩形 (MREC)	300 x 250
ISBannerSize_SMART	Smart Banner（自动渲染广告服务以调整 iPhone 和 iPad 的大小和方向）	If (iPhone ≤ 720) 320 x 50 If (iPad > 720) 728 x 90

步骤 2.请求横幅广告

覆盖 loadAdWithAdData 方法，允许发布者从您的网络请求横幅广告服务。ISAdData 允许您访问发布者输入并接收此过程所需的广告标识符，ISBannerSize 将指示请求的横幅大小。


- (void)loadAdWithAdData：(nonnull ISAdData *)adData   viewController：(UIViewController *)viewController         大小：(ISBannerSize *) 大小      delegate：(nonnull id)delegate<ISBannerAdDelegate>{}


public 覆盖 func loadAd(with adData:ISAdData、viewController：UIViewController，大小：ISBannerSize，委托：ISBannerAdDelegate){}

步骤 3.销毁横幅

IronSource 要求 app 开发者通过实现以下 destroyAdWithAdData 方法销毁横幅广告。


public void destroyAdWithAdData:(nonnull ISAdData *)adData {}


public 覆盖 func destroyAd(with adData:ISAdData）{}

注意

如果您的网络 SDK 不支持此类 API，则应添加一个空的实现。

步骤 4.报告 ISBannerAdDelegate 回调

根据网络的功能报告 ISBannerAdDelegate 回调。这将确保网络的性能数据在 IronSource 平台中正确反映。

强制回调


 // 指示横幅广告已成功加载 -(void)adDidLoadWithView:(UIView *) 视图 // 横幅广告加载失败。使用 ironSource ErrorTypes（无填充/其他）-(void)adDidFailToLoadWithErrorType:(ISAdapterErrorType)errorTypeerrorCode:(NSInteger)errorCode errorMessage:(nullable NSString*)errorMessage// 横幅广告成功显示给用户。这表明在 ironSource 平台上的展示量。 -(void)adDidOpen // 指示广告已单击 -(void)adDidClick


// 指示横幅广告已成功加载 public funcadDidLoad(_ bannerView：UIView) // 横幅广告加载失败。使用 ironSource ErrorTypes (No Fill / Other) public func adDidFailToLoadWith(_)errorType：ISAdapterErrorType、errorCode：Int, errorMessage：字符串 // 该横幅广告已成功向用户显示。这表明在 ironSource 平台上的印象。 public func adDidOpen() // 指示广告被点击 public func adDidClick()

注意

通道网络返回的横幅视图。

可选回调


//应在单击后、用户处于从 app 中取出 - (void)adWillLeaveApplication // 应调用广告视图呈现全屏内容后-（无效）adWillPresentScreen; -(void)adWillPresentScreen // 应在全屏内容之后调用已弃用 -（无效）adDidDismissScreen


//应在单击后和删除用户之前调用of the app - (void)adWillLeaveApplication // 应在广告之后调用视图呈现全屏内容-（无效）adWillPresentScreen; -(void)adWillPresentScreen // 应在全屏内容之后调用已弃用 -（无效）adDidDismissScreen

使用适配器访问发布者的输入

在自定义适配器注册过程中，您提供了 app 和 Instance 级别密钥。

这些键的值将由发布者根据 Unity LevelPlay 平台配置进行定义。通过使用 ISAdData 对象，这些值将在运行时可用。

ISAdData 对象包含一个包含配置值的映射，并且是适配器和广告单元类 API 的一部分。此参数在 init、loadAdWithAdData、showAdWithViewController 和 isAdAvailableWithAdData 方法中可用。

您可以使用在注册确认电子邮件中收到的名称访问 ISAdData 贴图结构中的值。


// 获取 Publisher 设置参数 NSString *appLevelParam1 = ISAdData.configuration[<YourAppLevelParam1>];NSString *instanceLevelParam1 = ISAdData.configuration[<YourInstanceLevelParam1>];NSString *instanceLevelParam2 = ISAdData.configuration[<YourInstanceLevelParam2>];


// 获取 Publisher 设置参数 self.appData = adData.getString(IS<YourNetworkName>CustomAdapter.<YourAppLevelParam>);self.instanceData1 = adData.getString(IS<YourNetworkName>CustomAdapter.<YourInstanceLevelParam1>);self.instanceData2 = adData.getString(IS<YourNetworkName>CustomAdapter.<YourInstanceLevelParam2>);

使用 ironSource 报错代码和报错类型

报错类型

这与 adDidFailToLoadWithErrorType 委托相关。

报错类型	描述
ISAdapterErrorTypeNoFill	没有可用广告显示时使用
ISAdapterErrorTypeInternal	用于网络报告的任何其他原因

错误代码

这些报错代码与 adDidFailToLoadWithErrorType 和 adDidFailToShowWithErrorCode 委托相关。

错误代码	描述
ISAdapterErrorMissingParams	操作失败，因为调用 API 时某些所需信息不可用
ISAdapterErrorAdExpired	用于指示广告是否已过期
ISAdapterErrorInternal	用于网络报告的任何其他报错

调试适配器（可选）

如果选择支持调试日志，请从 app 实现并调用 setAdapterDebug 方法。这应该作为 ISBaseNetworkAdapter 的一部分来完成。


- (void) setAdapterDebug:(BOOL) adapterDebug { }   _adapterDebug = adapterDebug;}


public 覆盖 func setAdapterDebug(_ adapterDebug:Bool) {self.adapterDebug = adapterDebug}

为 iOS 构构建自定义适配器

先决条件

为网络创建适配器

创建网络底部适配器

初始化网络 SDK

提供 SDK 和适配器版本

添加对插页式广告单元的支持

创建插页式广告单元类

请求插页式广告

检查广告是否可用

显示插页式广告

报告 ISInterstitialAdDelegate 回调

强制回调

可选回调

如何从底部适配器获取数据（可选）

添加对奖励视频广告单元的支持

创建奖励视频广告单元类

请求奖励视频广告

检查广告是否可用

显示奖励视频广告

报告 ISRewardedVideoAdDelegate 回调

强制回调

可选回调

如何从底部适配器获取数据（可选）

添加对横幅广告单元的支持

步骤 1.创建横幅广告单元类

横幅大小

ISBannerSize

描述

以点为单位的尺寸 (WxH)

步骤 2.请求横幅广告

步骤 3.销毁横幅

步骤 4.报告 ISBannerAdDelegate 回调

强制回调

可选回调

使用适配器访问发布者的输入

使用 ironSource 报错代码和报错类型

报错类型

报错类型

描述

错误代码

错误代码

描述

调试适配器（可选）