新一代SDK | 安卓对接
将Smaato作为首要广告服务器的对接说明
(安卓新一代SDK版本 21.3.6)
GDPR重要说明
作为媒体,您应该集成Consent Management Platform CMP(同意管理平台)和 IAB Europe’s Mobile In-App CMP API v1.0(IAB欧洲移动应用CMP v1.0). 您可以在以下网址找到基于web的CMP的参考实现和相应的原生包装器: GDPR-透明度-和-权限-框架.
如果您想嵌入自己的自定义CMP,则需要使用以下密钥以收集用户同意信息储存在 SharedPreferences
字段中:
密钥 | 值 | 描述 |
---|---|---|
IABConsent_CMPPresent |
Boolean |
如果应用程序中含有符合IAB规范的CMP,则设置为“YES”。 |
IABConsent_SubjectToGDPR |
String |
“ |
IABConsent_ConsentString |
String |
当使用符合IAB规范的CMP(同意管理平台)时,Base64编码的权限字符串,详见于Consent string and vendor list format v1.1(权限字符串和供应商名单格式v1.1) |
IABConsent_ParsedPurposeConsents |
String | 当使用符合IAB规范的CMP(同意管理平台)时,由“0 ”和“1 ”组成的字符串,位于位置N的字符说明了purposeID N的权限状态,详见于Global Vendor List(全球供应商名单) |
IABConsent_ParsedVendorConsents |
String |
当使用符合IAB规范的CMP(同意管理平台)时,由“0 ”和“1 ”组成的字符串,位于位置N的字符说明了verdorID N的权限状态,详见于Global Vendor List(全球供应商名单) |
IABConsent_SubjectToGDPR
被设为“1”,那么作为媒体的您需要使密钥IABConsent_ConsentString
包含有效的权限字符串(用户会在广告展示前被要求提供)。否则这样的广告请求会在服务器端被处理为掉且不会有返回。CCPA重要说明
加州消费者隐私法案(CCPA)的创建旨在为加州消费者提供更大的透明度和对其个人信息的控制。CCPA是美国首创的此类法规,旨在制定适用于加利福尼亚州管辖范围内开展业务的所有行业的广泛隐私和数据保护规则,而不是着眼于单个行业或特定数据收集和使用惯例。
有关CCPA法规的更多信息,请查看文章California Consumer Privacy Act (CCPA) – FAQ。您还可以查看IAB的美国隐私字符串文档。
如果您的产品有加利福尼亚州用户
作为开发者,您需要确保征询加利福尼亚州用户对私有数据传输的意见(同意或拒绝/选择退出或选择加入)。此答案应使用iAB US Privacy String格式以键“IABUSPrivacy_String
”保存在SharedPreferences
中。
Smaato新一代SDK会自动读取储存在SharedPreferences
中的信息。以下为代码样例。
SharedPreferences sharedPref = PreferenceManager.getDefaultSharedPreferences(context)
SharedPreferences.Editor editor = sharedPref.edit();
editor.putString("IABUSPrivacy_String", "1YNN"); // for example "1YNN"
editor.commit();
全屏广告位重要说明
目前,Smaato新一代SDK中,插屏广告兼容全屏广告位。在使用Smaato新一代SDK时,您需要在SPX中选择Interstitial (Display & Video)来变现您的全屏广告位。其余的所有选项此时都会无效。
请检查您的SPX账户中的Interstitial (Display & Video) 是否存在。如果您没有在广告格式的下拉菜单中看到Interstitial (Display & Video)选项,请联系您的Smaato客户经理启动该选项。
- 当在SPX中创建您的全屏广告位时,选择广告格式中的Interstitial (Display & video)选项。 (图片1)
- 对于广告素材类型,您有三种选项:(图片2):
- Display Only将只支持富媒体广告。
- Video Only将只支持视频广告。
- Display and Video会支持富媒体和视频广告。
图片1:广告格式下拉选项
图片2:广告素材类型下拉选项
广告测试
Publisher ID: 1100042525 |
广告位ID | 类型 | 描述 |
---|---|---|
130626424 | 富媒体 | 横幅广告/中等矩形/Leaderboard/Skyscraper |
130635694 | 静态图 | 横幅广告/中等矩形/Leaderboard/Skyscraper |
130635706 | MRAID | 横幅广告/中等矩形/Leaderboard/Skyscraper |
130626426 | 富媒体/视频 | 插屏(视频(有end-card) +富媒体插屏320×480,480×320,1024×768 & 768×1024) |
130626427 | 视频 | 可跳过视频 |
130626428 | 激励广告 | 激励视频 |
130635048 | 激励广告 | 激励视频(无end-card) |
对接安卓应用
1.) 在SPX建立一个账户
2.) 设置您的Android项目
2.1) 添加以下储存库设置到您项目的主build.gradle文件中:
allprojects {
repositories {
google()
jcenter()
maven {
url "https://s3.amazonaws.com/smaato-sdk-releases/"
}
}
}
2.2) 设定编译选项为Java 8,(将下列语句放入您应用模块中的build.gradle文件中):
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
2.3) 请将以下代码添加到build.gradle文件中作为依赖关系。
对于所有广告类型,以下依赖关系都需要设置完成:
implementation 'com.smaato.android.sdk:smaato-sdk:21.3.6'
对于横幅广告,以下依赖关系都需要设置完成:
implementation 'com.smaato.android.sdk:smaato-sdk-banner:21.3.6'
对于Interstitial ads,以下依赖关系都需要设置完成:
implementation 'com.smaato.android.sdk:smaato-sdk-interstitial:21.3.6'
对于Rewarded ads,以下依赖关系都需要设置完成:
implementation 'com.smaato.android.sdk:smaato-sdk-rewarded-ads:21.3.6'
2.4) 添加下列权限到您应用中的AndroidManifest.xml
文件:
强制性权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
选择性权限:
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
2.5) 如果您的应用面向安卓5.0 (API等级21) 或者更高,需要添加以下语句到您应用中的AndroidManifest.xml
文件:
<uses-feature android:name="android.hardware.location.network" />
2.6) 如果您的应用面向安卓9 Pie (API等级28) 或者更高,为了发送HTTP请求(投放更多广告),需要配置AndroidManifest.xml
文件中application标签里的 networkSecurityConfig
属性:
android:networkSecurityConfig="@xml/network_security_config"
2.7) 然后在XML resource目录中创建network_security_config.xml
:
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
<base-config cleartextTrafficPermitted="true" />
</network-security-config>
更多细节请参考Network security configuration, 官方Google文件链接:https://developer.android.com/training/articles/security-config
3.) 在您的应用中初始化Smaato SDK
3.1) 初始化Smaato SDK,请将以下语句添加到您的Application.OnCreate()
方法中:
SmaatoSdk.init(this, publisherId);
3.2) 您可以通过传递Config参数到init方法来为SDK配置额外的参数。
Config config = Config.builder()
.setLogLevel(LogLevel.INFO)
.setHttpsOnly(false)
.build();
SmaatoSdk.init(this, config, publisherId);
3.3) 此外,如果您有用户信息,我们推荐您通过以下接口传递给Smaato SDK:
SmaatoSdk.setKeywords(...);
SmaatoSdk.setSearchQuery(...);
SmaatoSdk.setGender(...);
SmaatoSdk.setAge(...);
SmaatoSdk.setLatLng(...);
SmaatoSdk.setRegion(...);
SmaatoSdk.setLanguage(...);
SmaatoSdk.setZip(...);
SmaatoSdk.setCoppa(...);
SmaatoSdk.setGPSEnabled(...);
SmaatoSdk.setWatermarkEnabled(...);
4.) 展示横幅广告
4.1) 添加BannerView
到您的layout.xml中:
<com.smaato.sdk.banner.widget.BannerView
android:id="@+id/bannerView"
android:layout_width="wrap_content"
android:layout_height="wrap_content" />
4.2) 在Activity/Fragment中,使用上述设计,获取BannerView
:
BannerView bannerView = (BannerView) findViewById(R.id.bannerView);
4.3) 使用您的adspaceId
和对应的bannerAdSize
调用loadAd()
来开始加载广告:
bannerView.loadAd(adspaceId, bannerAdSize);
不同横幅广告尺寸的示例:
loadAd(adSpaceId, BannerAdSize.XX_LARGE_320x50);
loadAd(adSpaceId, BannerAdSize.MEDIUM_RECTANGLE_300x250);
loadAd(adSpaceId, BannerAdSize.LEADERBOARD_728x90);
loadAd(adSpaceId, BannerAdSize.SKYSCRAPER_120x600);
4.4) 可选,auto-reload间隔可以通过使用下列语句改变(默认值为60秒):
bannerView.setAutoReloadInterval(...);
4.5) 可选, 您也可以通过设定BannerView.EventListener
来监听有关广告状态的事件:
bannerView.setEventListener(new BannerView.EventListener() {
@Override
public void onAdLoaded(@NonNull BannerView bannerView) {}
@Override
public void onAdFailedToLoad(@NonNull BannerView bannerView, @NonNull BannerError bannerError) {}
@Override
public void onAdImpression(@NonNull BannerView bannerView) {}
@Override
public void onAdClicked(@NonNull BannerView bannerView) {}
@Override
public void onAdTTLExpired(@NonNull BannerView bannerView) {}
});
4.6) 当您的UI元件(负责BannerView
)被销毁时,为了正常释出BannerView
来源,BannerView.destroy()
应被调用:
class YourActivity {
...
@Override
public void onDestroy() {
super.onDestroy();
bannerView.destroy();
}
}
5.) 展示插屏广告
5.1) 使用您的adspaceId
和eventListener
调用loadAd()
来加载广告:
Interstitial.loadAd(adspaceId, eventListener);
eventListener
保留了{@link java.lang.ref.WeakReference}
。这是SOMA SDK使用者的责任来持有一个传递的eventListener
,避免被垃圾收集器收集。5.2) EventListener
会被用来监听广告状态改变的事件:
public interface EventListener {
/**
* 当广告响应成功会触发此方法。
* <p>
* 仅在主线程中触发。
*/
void onAdLoaded(@NonNull InterstitialAd interstitialAd);
/**
* 当广告请求失败或没有填充会触发此方法。
* <p>
* 仅在主线程中触发。
*
* @param interstitialRequestError {@link InterstitialRequestError} the error.
*/
void onAdFailedToLoad(@NonNull InterstitialRequestError interstitialRequestError);
/**
* 当广告加载或展示失败会触发此方法。
* <p>
* 仅在主线程中触发。
*
* @param interstitialError {@link InterstitialError} the error.
*/
void onAdError(@NonNull InterstitialAd interstitialAd, @NonNull InterstitialError interstitialError);
/**
* 当插屏广告被打开会触发此方法。
* <p>
* 仅在主线程中触发。
*/
void onAdOpened(@NonNull InterstitialAd interstitialAd);
/**
* 当插屏广告关闭会触发此方法。
* <p>
* 仅在主线程中触发。
*/
void onAdClosed(@NonNull InterstitialAd interstitialAd);
/**
* 当用户点击广告会触发此方法。
* <p>
* 仅在主线程中触发。
*/
void onAdClicked(@NonNull InterstitialAd interstitialAd);
/**
* 当广告被展示会触发此方法。
* <p>
* 仅在主线程中触发。
*/
void onAdImpression(@NonNull InterstitialAd interstitialAd);
/**
* 当广告过期会触发此方法。
* <p>
* 仅在主线程中触发。
* <p>
*
* @param interstitialAd {@link InterstitialAd} advertisement object View that received onAdTtlExpired event
*/
void onAdTTLExpired(@NonNull InterstitialAd interstitialAd);
}
5.3) 可选,您可以改变插屏广告
的背景颜色(默认为黑色):
interstitialAd.setBackgroundColor(0xff123456);
5.4) 在接收到的InterstitialAd
对象上调用showAd(activity)
:
new EventListener() {
@Override
public void onAdLoaded(@NonNull InterstitialAd interstitialAd) {
interstitialAd.showAd(activity);
}
...
};
6.) 展示激励插屏广告
6.1) 使用您的adspaceId
和EventListener
调用RewardedInterstitial.loadAd()
来加载激励插屏广告:
RewardedInterstitial.loadAd(adspaceId, eventListener);
eventListener
中保留了{@link java.lang.ref.WeakReference}
。这是SOMA SDK使用者的责任来持有一个传递的eventListener
,避免被垃圾收集器收集。6.2) 关于插屏,EventListener
会被用来监听广告状态改变的事件:
/**
* 一个提供{@link RewardedInterstitial#loadAd}请求的监听器。
* <p>
* 事件始终在主线程上传递。
*/
public interface EventListener {
/**
* 当广告响应成功会触发此方法。
* <p>
* 仅在主线程中触发。
*/
void onAdLoaded(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
/**
* 当广告请求失败或没有填充时会触发此方法。
* <p>
* 仅在主线程中触发。
*
* @param rewardedRequestError {@link RewardedRequestError}失败的请求数据对象含有
* 广告请求参数:publisherId, adspaceId
* 和rewardedAdError {@link RewardedError}
*/
void onAdFailedToLoad(@NonNull RewardedRequestError rewardedRequestError);
/**
* 当广告展示失败会触发此方法。
* <p>
* 仅在主线程中触发。
*
* @param rewardedInterstitialAd {@link RewardedInterstitialAd} 获取onClose事件的广告对象
* @param rewardedError {@link RewardedError}
*/
void onAdError(@NonNull RewardedInterstitialAd rewardedInterstitialAd, @NonNull RewardedError rewardedError);
/**
* 当用户关闭广告时会触发此方法。
* <p>
* 仅在主线程中触发。
* <p>
* {@link RewardedInterstitialAd} 获取onClose事件的广告对象
*/
void onAdClosed(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
/**
* 当用户点击广告时会触发此方法。
* <p>
* 仅在主线程中触发。
* <p>
* {@link RewardedInterstitialAd} 获取onClick事件的广告对象
*/
void onAdClicked(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
/**
* 当广告回放开始时会触发此方法。
* <p>
* 仅在主线程中触发。
* <p>
* {@link RewardedInterstitialAd} 获取onStart事件的广告对象
*/
void onAdStarted(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
/**
* 当广告成功回放完毕会触发此方法。
* <p>
* 仅在主线程中触发。
* <p>
* {@link RewardedInterstitialAd} 获取onRewarded事件的广告对象
*/
void onAdReward(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
/**
* 当广告过期会触发此方法。
* <p>
* 仅在主线程中触发。
* <p>
* {@link RewardedInterstitialAd} 获取onTtlExpired事件的广告对象
*/
void onAdTTLExpired(@NonNull RewardedInterstitialAd rewardedInterstitialAd);
}
6.3) 当广告已加载完成并准备展示时,可以对一个接收到的RewardedInterstitialAd
对象调用show()
:
EventListener eventListener = new EventListener() {
@Override
public void onAdLoaded(@NonNull RewardedInterstitialAd rewardedInterstitialAd) {
rewardedInterstitialAd.show();
}
...
}
Modified: March 1, 2021 at 11:43 am