为 Android 构构建自定义适配器
在 Android 上为网络开发和集成自定义适配器以启用广告聚合。
阅读时间1 分钟最后更新于 3 天前
本文档介绍构建自定义适配器的步骤，并向发布者提供将网络与 ironSource 聚合集成所需的资源。
先决条件
- 填写自定义适配器注册表
- 确保您拥有以下可用信息：
- 适配器软件包称
- 适配器类名称
- 网络配置密钥
- 在此处下载最新的 LevelPlay SDK
- 最低要求 LevelPlay SDK 版本为 7.1.13，适用于奖励视频和插页式广告单位。
注意
对于 Android 和 Unity 开发的项目，所需的最低 LevelPlay SDK
横幅广告单元的版本为 7.3.0
重要
- 确保在代码中处理主线程要求
- 确保添加代码保护和异常处理以保护应用程序免受意外故障的影响。
如何为网络创建适配器
您的网络适配器将管理网络广告逻辑，允许发布者使用 ironSource 聚合展示来自您的网络的广告服务。
在此过程中，您需要创建一个适配类，称为 BaseAdapter，并为要支持的每个广告单元创建一个额外的类。
BaseAdapter 将帮助您管理网络的 SDK，包括 SDK 初始化过程，并允许您定义在整个会话中可用于所有广告单位的变量和常量。
广告单元类将确定加载、展示和管理广告的逻辑，并将针对瀑布流中的每个广告展示进行实例化。
创建网络底部适配器
要实现网络适配器，请通过扩展 ironSource BaseAdapter 类在专用软件包中创建一个新类
使用您在自定义适配器注册确认电子邮件中收到的软件包和底部适配器名称。
软件包 com. ironsource.adapters.custom.<YourNetworkName>;public class <YourNetworkName>CustomAdapter extends BaseAdapter { // Your class implementation}
初始化网络 SDK
ironSource 聚合将在聚合中的任何初始化过程中调用底部适配器的初始化 API。因此，可能会多次调用此 API。
作为 init 实现的一部分，确保在时间 NetworkInitializationListener 中定义的初始化回调。
AdData 参数将包含发布者提供给 ironSource 的配置数据。在此处了解有关 AdData 类的更多信息。
void init(@NotNull AdData adData, @NotNull Context context, @Nullable NetworkInitializationListener listener){ ... if (init-success-condition) { // Initialization completed successfully listener.onInitSuccess(); } else { // Initialization failed listener.onInitFailed(AdapterErrors.ADAPTER_ERROR_MISSING_PARAMS, error); }}
提供 SDK 和适配器版本
此信息将指示发布者的 app 上当前实现了哪些 SDK 和适配器版本。在实现 getNetworkSDKVersion 时，我们建议使用 API 而不是硬编码值，以便更灵活地更新适配器和 SDK 支持。
@Nullable 字符串 getNetworkSDKVersion();@NotNull 字符串 getAdapterVersion();
添加对插页式广告单元的支持
创建插页式广告单元类
创建一个类，通过扩展 BaseInterstitial 类**来管理插页式广告单元，**作为网络自定义适配器的同一软件包的一部分。当发布者通过 加载 API 在app程序中触发新的插页式广告时，类将被激活。
在注册过程中使用从 ironSource 收到的软件包和插页类名称。
软件包 com. ironsource.adapters.custom.[YourNetworkName];public class SampleCustomInterstitial extends BaseInterstitial<SampleCustomAdapter> implements SampleNetworkInterstitialAdListener {public class <YourNetworkName>CustomInterstitial extendsBaseInterstitial <<YourNetworkNameCustomAdapter>> {...}
实现广告单元构造函数
使用 NetworkSetting 对象实现构造函数。这是在插页式广告单元实现过程中必需的，它将确保您的网络可以添加到瀑布流中。
public <YourNetworkName>CustomInterstitial(NetworkSettings networkSettings) { super(networkSettings);}
请求插页式广告
覆盖 LoadAd API 以允许发布者从您的网络请求插页广告服务。AdData 允许您访问发布者的输入并接收广告标识符。
请确保实现 InterstitialAdListener 回调，以便成功加载广告 (onAdLoadSuccess) 和任何类型的失败 (onAdLoadFailed)。如果监听器回调在预定义时间后未触发，则冥想将停止加载，并且网络将无法提供广告。
public void loadAd(AdData adData, Activity activity, InterstitialAdListener listener) { // Load your ad}
检查广告是否可用
覆盖 isAdAvailable API，允许发布者在尝试向用户展示广告之前检查广告的准备情况。如果成功加载广告，API 应返回 true，如果当前未加载广告，则返回 false。为此，可以使用网络的 is-ad-available 指示（如果网络提供），或者手动管理广告状态作为 LoadAd 和 ShowAd API 的一部分。
public boolean isAdAvailable(AdData adData) { return isAdAvailable;}
显示插页式广告
成功加载广告后，发布者应该能够显示该广告。在验证 isAdAvailable 为 true 后，可以覆盖 showAd API，从而为发布者提供更好的体验。此方法收到的部分信息是 AdData。使用此对象时，将允许您展示相关广告。如果无法执行显示，则应返回 onAdShowFailed 回调。
public void showAd(AdData adData, InterstitialAdListener listener) { // check your ad load status if (isAdLoaded) { // show your ad } else { listener.onAdShowFailed(adatperErrorCode, adapterErrorMsg); }}
报告 InterstitialAdListener 回调
确保根据网络的功能覆盖 InterstitialAdListener 的回调。正确报告回调将确保 ironSource 聚合的最佳实践流程，并启用网络性能数据在 ironSource 平台中正确反映。
强制回调
// Indicates that interstitial ad was loaded successfullyvoid onAdLoadSuccess();// The interstitial ad failed to load.使用 ironSource ErrorTypes（无填充/其他）void onAdLoadFailed(@NotNull AdapterErrorType adapterErrorType, int errorCode, @Nullable String errorMessage);// The interstitial ad is displayed successfully to the user.这表示展示量。void onAdOpened();// User closed the interstitial advoid onAdClosed();// The ad could not be displayedvoid onAdShowFailed(int errorCode, @Nullable String errorMessage);
可选回调
// Indicates the network differentiates between show-success and ad-open (impression)void onAdShowSuccess();// Indicates an ad was clickedvoid onAdClicked();
如何从底部适配器获取数据（可选）
如果您的底部适配器通过会话管理与广告单位相关的状态或参数，请使用 getNetworkAdapter API。这包括任何定义为底部适配器一部分的对象，这些对象应在广告单元 API 中使用。
// example of data retrieved from your network level adapterSampleCustomAdapter networkAdapter = getNetworkAdapter();if (networkAdapter != null) { // call network level method String extraData = networkAdapter.sampleAppLevelData();}
添加对奖励视频广告单元的支持
创建奖励视频广告单元类
创建一个类，通过扩展 BaseRewardedVideo 类**来管理奖励视频广告单元，**作为网络自定义适配器的同一软件包的一部分。当发布者通过 加载 API 在app中触发新的奖励视频广告时，类将被激活。
使用您在注册过程中从 Ironsource 收到的资源软件包和奖励视类名称。
软件包 com. ironsource.adapters.custom.[YourNetworkName];import com.ironsource.mediationsdk.adunit.adapter.BaseRewardedVideo;import com.ironsource.mediationsdk.adunit.adapter.listener.RewardedVideoAdListener;import com.ironsource.mediationsdk.adunit.adapter.utility.AdData;import com.ironsource.mediationsdk.adunit.adapter.utility.AdapterErrorType;import com.ironsource.mediationsdk.adunit.adapter.utility.AdapterErrors;import com.ironsource.mediationsdk.model.NetworkSettings;
public class SampleCustomRewardedVideo extends BaseRewardedVideo<SampleCustomAdapter> implements SampleNetworkRewardedVideoListener { // Add your adapter code here}
实现广告单元构造函数
使用 NetworkSetting 对象实现构造函数。这是在奖励视频广告单元实现过程中必需的，它将确保您的网络可以添加到瀑布流中。
public <YourCustomNetwork>CustomRewardedVideo(NetworkSettings networkSettings) { super(networkSettings);}
请求奖励视频广告
覆盖 LoadAd API 可允许发布者从您的网络请求奖励视频广告服务。AdData 允许您访问发布者的输入并接收广告标识符。
请确保实现 RewardedVideoAdListener 回调，以便成功加载广告 (onAdLoadSuccess) 和任何类型的失败 (onAdLoadFailed)。如果监听器回调在预定义时间后未触发，则冥想将停止加载，并且网络将无法提供广告。
public void loadAd(@NotNull AdData adData, @NotNull Activity activity, @NotNull RewardedVideoAdListener rewardedVideoAdListener) { // Load your ad}
检查广告是否可用
覆盖 isAdAvailable API，允许发布者在尝试向用户展示广告之前检查广告的准备情况。如果成功加载广告，API 应返回 true，如果当前未加载广告，则返回 false。为此，可以使用网络的 is-ad-available 指示（如果网络提供），或者手动管理广告状态作为 LoadAd 和 ShowAd API 的一部分。
public boolean isAdAvailable(AdData adData) { return isAdAvailable;}
显示奖励视频广告
成功加载广告后，发布者应该能够显示该广告。在验证 isAdAvailable 为 true 后，可以覆盖 showAd API，从而为发布者提供更好的体验。此方法收到的部分信息是 AdData。使用此对象时，将允许您展示相关广告。如果无法执行显示，则应返回 onAdShowFailed 回调。
public void showAd(AdData adData, RewardedVideoAdListener rewardedVideoAdListener) { // check your ad load status if (isAdLoaded) { // show your ad } else { AdapterErrors adapterErrorCode = AdapterErrors.<ERROR CODE>; 字符串 adapterErrorMsg = “报错消息”; rewardVideoAdListener.onAdShowFailed(adatperErrorCode, adapterErrorMsg); }}
报告 RewardedVideoAdListener 回调
确保根据网络的功能覆盖 RewardedVideoAdListener 的回调。正确报告回调将确保 ironSource 聚合的最佳实践流程，并启用网络性能数据在 ironSource 平台中正确反映。
强制回调
// Indicates that rewarded video ad was loaded successfullyvoid onAdLoadSuccess();// The rewarded video ad failed to load.使用 ironSource ErrorTypes（无填充/其他）void onAdLoadFailed(@NotNull AdapterErrorType adapterErrorType, int errorCode, @Nullable String errorMessage);// The rewarded video ad is displayed successfully to the user.这表示在 ironSource 平台上的展示量。void onAdOpened();// User closed the rewarded video advoid onAdClosed();// The ad could not be displayedvoid onAdShowFailed(int errorCode, @Nullable String errorMessage);// The ad was rewarded successfullyvoid onAdRewarded();
可选回调
// Indicates an ad was clickedvoid onAdClicked();// Indicates an ad was displayed on foregroundvoid onAdVisible();// Indicates an ad playable startedvoid onAdStarted();// Indicates an ad playable endedvoid onAdEnded();
添加对横幅广告单元的支持（仅限 Android 开发的应用程序）
步骤 1。创建横幅广告单元类
创建一个类来管理横幅广告单元，方法是将 BaseBanner 类扩展为网络自定义适配器的同一软件包的一部分。当发布者通过 加载 API 在app程序中触发新的横幅广告时，类将被激活。
在注册过程中使用从 ironSource 收到的软件包和横幅类名称。
步骤 2.实现广告单元构造函数
使用 NetworkSetting 对象实现构造函数。这是在横幅广告单元实现过程中必需的，它将确保您的网络可以添加到瀑布流中。
public <YourNetworkName>CustomBanner(NetworkSettings networkSettings) { super(networkSettings);}
横幅大小
请参阅下表以了解我们支持的横幅大小的详细信息。自定义网络可能支持这些大小的任意组合。横幅大小将作为参数接收，作为 loadAd API 的一部分。
当收到的横幅大小为 **SMART 时，**请确保根据设备屏幕大小将大小更改为 BANNER 或 LEADERBOARD（请参阅以下说明）。
ISBannerSize | 描述 | 尺寸（以 dp（宽高）为单位） |
|---|---|---|
| BANNER | 标准横幅 | 320 x 50 |
| 大 | 大横幅 | 320 x 90 |
| 矩形 | 中等矩形 (MREC) | 300 x 250 |
| SMART | Smart Banner（针对移动端和平板电脑进行调整） | 如果 (Screen width ≤ 720) 320 x 50 如果 (Screen width > 720) 728 x 90 |
步骤 3.请求横幅广告
实现 loadAd API 可允许发布者从您的网络请求横幅广告服务。AdData 允许您访问发布者的输入并接收广告标识符，ISBannerSize 将指示请求的横幅大小。
public void loadAd(@NotNull AdData adData, @NotNull Activity activity, @NotNull ISBannerSize bannerSize, @NotNull BannerAdListener bannerAdListener) { // Load your ad}
步骤 4.销毁横幅
IronSource 要求 app 开发者通过实现以下 destroyAd 方法销毁横幅广告。
public void destroyAd(@NotNull AdData adData) { }
注意
如果您的网络 SDK 不支持此类 API，则应添加一个空的
实现。
步骤 5。报告 BannerAdListener 回调
根据网络的功能报告 BannerAdListener 的回调。这将确保网络的性能数据在 IronSource 平台中正确反映。
强制回调
// Indicates that a banner ad was loaded successfullyvoid onAdLoadSuccess(@NotNull View adView, @NotNull FrameLayout.LayoutParams frameLayoutParams)// The banner ad failed to load.使用 ironSource ErrorTypes（无填充/其他）void onAdLoadFailed(@NotNull AdapterErrorType adapterErrorType, int errorCode, @Nullable String errorMessage)// The banner ad is displayed successfully to the user.这表示在 ironSource 平台上的展示量。void onAdOpened()// Indicates an ad was clickedvoid onAdClicked()
定义由自定义适配器中的网络传递给 onAdLoadSuccess 回调的 LayoutParams 对象的值。下面列出了最佳实践：
- 通道实际横幅大小的宽度和高度。
- 将重力属性定义为重力。CENTER。
可选回调
//Should be invoked after a click, and before the user is taken out of the appvoid onAdLeftApplication()// Should be invoked after the ad view presents fullscreen contentvoid onAdScreenPresented()// Should be invoked after the fullscreen content is dismissedvoid onAdScreenDismissed()
使用适配器访问发布者的输入
在自定义适配器注册过程中，您提供了 app 和实例级密钥。
这些键的值将由发布者在 IronSource 平台上定义。通过使用 AdData 对象，这些值将在运行时可用。
AdData 对象包含一个包含配置值的映射，并且是适配器和广告单元类 API 的一部分。此参数在 Init、LoadAd、ShowAd 和 isAdAvailable API 中可用。
您可以使用在注册确认电子邮件中收到的名称访问 AdData 贴图结构中的值。
// Get Publisher setup parametersfinal 字符串 appLevelParam1 = adData.getString(<YourAppLevelParam1>);final String instanceLevelParam1 = adData.getString(<YourInstanceLevelParam1>);final String instanceLevelParam2 = adData.getString(<YourInstanceLevelParam2>);
使用 ironSource 报错代码和报错类型
报错类型
这与 onAdLoadFailed 回调相关。
报错类型 | 描述 |
|---|---|
| 没有可用广告显示时使用 |
| 用于网络报告的任何其他原因 |
错误代码
这些报错代码与 onAdLoadFailed 和 onAdShowFailed 回调相关。
错误代码 | 描述 |
|---|---|
| 操作失败，因为调用 API 时某些所需信息不可用 |
| 用于指示广告是否已过期 |
| 用于网络报告的任何其他报错 |
调试适配器（可选）
如果选择支持调试日志，请从app程序实现并调用 setAdapterDebug API。这应该作为 BaseAdapter 的一部分来完成。
public class <YourNetworkName>CustomAdapter extends BaseAdapter { @Override public void setAdapterDebug(boolean adapterDebug) { this.adapterDebug = adapterDebug; }}