接入文档 2.1 - uc-union/union-ads-sdk-demo GitHub Wiki

Union广告SDK开发者接入文档

1.术语定义

术语 / 定义 英文对应词 含义
开发者 App Developer 应用开发者
广告提供商 AD Provider 广告提供商
渠道标识 Pub id 对应不同广告类型的标识.如使用banner、插屏广告，在设置渠道标识时就要设置对应类型的Pub id

2.功能简介

广告SDK 旨在帮助应用开发者简单，快捷的接入广告功能，应用开发者只需简单几步操作即可完成不同类型的广告接入。 目前广告SDK支持条幅广告（Banner)， 插屏广告(Interstitial Ad)以及原生广告(Native Ad)。

  • 条幅广告是以Android View的形式提供给应用开发者，开发者可以自定义其位置，大小。
  • 插屏广告是以插入型UI（半屏对话框或者全屏UI）的形式展现，用户需要完成该UI的交互之后才能回到应用界面。
  • 原生广告则是将广告素材（文字，图片等）提供给应用开发者，由开发者自定义其展现形式的广告。

3.总体接入流程

如下为广告SDK接入开发流程，请严格按照流程接入。

接入流程图

4.环境配置

最低系统要求为Android 11。

目前Union广告SDK支持Facebook, Google和Union三个广告网络，开发者可以选择性的接入其中的一个或多个。

4.1设置依赖工程及依赖库

接入不同广告网络需要执行的操作如下：

Google: 将Demo中的goole_play_service_lib工程导入Eclipse，并设置应用程序工程依赖此工程

Facebook: 拷贝Demo工程libs目录下的audiencenetwork-x.x.x.jar及 android-support-v4.jar

Union: 拷贝Demo工程libs目录下的unionads-x.x.x.jar

注意：广告SDK本次发布支持的是FaceBook广告SDK的4.8.2版本，请不要下载其他版本替换。

4.2配置AndroidManifest.xml文件

  1. 加入相关权限设置

        <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

  2. 在application节点中加入google ad和facebook ad相关的meta-data和Activity信息。

接入不同广告网络需要执行的操作如下：

Google: 在标签中加入以下子标签：

<meta-data
  android:name="com.google.android.gms.version"
  android:value="@integer/google_play_services_version" />
<activity
  android:name="com.google.android.gms.ads.AdActivity"
  android:configChanges="keyboard|keyboardHidden|orientation|
screenLayout|uiMode|screenSize|smallestScreenSize"
  android:theme="@android:style/Theme.Translucent" />

Facebook: 在标签中加入以下子标签：

<activity
  android:name="com.facebook.ads.InterstitialAdActivity"
  android:configChanges="keyboardHidden|orientation|screenSize" />

Union: 无

##4.3配置代码混淆规则 接入不同广告网络需要在混淆配置文件中加入的内容如下：

Google:

# For Google Play Services
-keep public class com.google.android.gms.ads.**{
   public *;
}
# For ads classes
-keep public class com.google.ads.**{
   public *;
}

Facebook:

#For Facebook classes
-keep public class com.facebook.ads.**{
   public *;
}

Union:

-keep public class au.gp.** { *; }
-dontwarn com.ucweb.union.**
-keep class com.ucweb.union.** { *; }

5. API接口说明

5.1 API使用说明

注意：必须在应用程序Application的onCreate中调用UnionAdsSdk.start以启动和初始化广告SDK，如果没有Application,请创建一个。

5.1.1 条幅广告(Banner)

注意： 目前条幅广告仅支持源码调用方式的API, 不支持直接在xml文件中配置的使用方式。

广告SDK以AndroidView的形式提供条幅广告，以方便应用开发者可以灵活的设置广告的位置和大小。 条幅广告的使用代码示例如下：

final BannerAdView adView = new BannerAdView (MainActivity.this);
adView.setAdListener(new AdListener() {
    @Override
    public void onAdOpened(UnionAd arg0) {}
    @Override
    public void onAdLoaded(UnionAd arg0) {}
    @Override
    public void onAdError(UnionAd arg0,AdError arg1) {}
    @Override
    public void onAdClosed(UnionAd arg0) {}
    @Override
    public void onAdClicked(UnionAd arg0) {}
});
AdRequest adRequest = AdRequest.newBuilder()
        .pub("ssr@magicdimMediationBanner")
        .build();
adView.loadAd(adRequest);

5.1.2 插屏广告(Interstitial)

广告SDK以弹出对话框获或全屏UI的形式提供插屏广告。

插屏广告的使用代码示例如下：

注意：在onAdLoaded的时候要调用广告InterstitialAd的show方法，否则广告不会展示。

final InterstitialAd interstitial = new InterstitialAd(MainActivity.this);  
interstitial.setAdListener(new AdListener() {
    @Override
    public void onAdOpened(UnionAd arg0) {}
    @Override
    public void onAdLoaded(UnionAd arg0) {
        interstitial.show();
    }
    @Override
    public void onAdError(UnionAd arg0,AdError arg1) {}
    @Override
    public void onAdClosed(UnionAd arg0) {}
    @Override
    public void onAdClicked(UnionAd arg0) {}
});
AdRequest adRequest = AdRequest.newBuilder()
        .pub("ssr@magicdimMediationInt")
        .build();
interstitial.loadAd(adRequest);

5.1.3 原生广告(Native Ad)

原生广告是广告SDK提供的可定制性最强的广告，广告SDK只将广告相关的资源返回给应用开发者，由应用开发者自定义其位置，大小和排版。需要注意的是，由于广告SDK内部需要处理一些广告相关的事件，需要应用开发者通过registerViewForInteraction将最终展现广告的View与原生广告关联起来。

原生广告在发起请求的时候如果使用AdRequestOption.requestCoverImageSize指定广告的大小（广告封面大图的大小），广告SDK会找出与该尺寸最接近的广告返回。

默认情况下，原生广告是会下载好封面大图的图片资源（如果有）的，如果在发起请求的时候指定不需要请求封面大图(使用AdRequestOption.requestExtraResource)，则广告SDK就不会下载该封面大图，用户需要自行下载。

原生广告的使用代码示例如下：

final NativeAd nativeAd = new NativeAd(
        MainActivity.this);
nativeAd.setAdListener(new AdListener() {
    @Override
    public void onAdOpened(UnionAd arg0) {}
    @Override
    public void onAdLoaded(UnionAd arg0) {
        demoNativeAdView.refreshData(nativeAd.getNativeAdAssets());    }
    @Override
    public void onAdError(UnionAd arg0, AdError arg1) { }
    @Override
    public void onAdClosed(UnionAd arg0) {}
    @Override
    public void onAdClicked(UnionAd arg0) {}
});
AdRequest adRequest = AdRequest.newBuilder()
        .pub("ssr@magicdimMediationNative")
        .testDeviceId("AA530D8B0E733C16F937E17EBF757DF6")
        .withOption(AdRequestOption.newNativeBuilder()
                          .requestCoverImageSize(300, 50)
                          .requestExtraResource(true)
                          .build())
        .build();
nativeAd.loadAd(adRequest);

DemoNativeAdView实现如下，具体可参考Demo:

注意：registerViewForInteraction将广告与展示广告的View关联起来。

public class DemoNativeAdView extends FrameLayout {
	private LinearLayout mContainer;

	private TextView mTvTitle;
	private TextView mTvDescription;
	private ImageView mIvIcon;
	private ImageView mIvCover;
	private NativeAd mNativeAd;

	public DemoNativeAdView(Context context) {
		super(context);
		initView(context);
	}

	public void attach(NativeAd nativeAd) {
		mNativeAd = nativeAd;
	}

	private void initView(Context context) {
		mTvTitle = new TextView(context);
		mTvDescription = new TextView(context);
		mIvIcon = new ImageView(context);
		mIvCover = new ImageView(context);
		mContainer = new LinearLayout(context);
		{
			mContainer.setOrientation(LinearLayout.VERTICAL);
			LinearLayout.LayoutParams wwll = new LinearLayout.LayoutParams(
					LinearLayout.LayoutParams.WRAP_CONTENT,
					LinearLayout.LayoutParams.WRAP_CONTENT);
			mContainer.addView(mTvTitle, wwll);
			mContainer.addView(mTvDescription, wwll);
			mContainer
					.addView(mIvIcon, new LinearLayout.LayoutParams(100, 100));
			mContainer
					.addView(mIvCover, new LinearLayout.LayoutParams(300, 50));
		}

		addView(mContainer);
	}

	public void refreshData(NativeAdAssets info) {
		if (mNativeAd != null) {
			mNativeAd.registerViewForInteraction(this, mTvTitle,
					mTvDescription, mIvIcon, mIvCover);
		}
		if (info != null) {
			mTvTitle.setText("Title:" + info.getTitle());
			mTvDescription.setText("Description:" + info.getDescription());

			UIUtils.setBackgroundDrawable(mIvIcon,
					info.getIcon() == null ? null : info.getIcon()
							.getDrawable());
			UIUtils.setBackgroundDrawable(mIvCover,
					info.getCover() == null ? null : info.getCover()
							.getDrawable());
		}
	}
}

5.2 API相关接口类及参数说明

5.2.1 UnionAdsSdk

UnionAdsSdk是广告SDK的初始化控制类，主要用于对SDK的初始化， 必须在程序Application的onCreate中调用。

主要接口及参数说明：

public static void start(Context context)

使用：广告SDK的初始化函数， 在Android应用程序Application的onCreate里调用。
参数： Context： Android应用的Application Context

5.2.2 AdRequest

AdRequest标识一个广告请求，用户可以通过AdReques.Builder设置广告请求的参数并生成。

AdRequest.Builder主要接口及参数说明：

public static Builder pub(String pub)

使用：设置广告请求对应的pub。
参数：

pub： 要请求的广告对应的pub标识

返回值：AdRequest.Builder实例对象。

public static Builder testDeviceId(String testDeviceId)

使用：设置广告请求需要的testDeviceId
参数：

testDeviceId： 通常是第三方广告SDK（facebook等）的测试请求参数，一般SDK会从Logcat输出相关testDeviceId的提示信息。

返回值： AdRequest.Builder实例对象。

public static Builder withOption(AdRequestOption option)

使用：设置广告请求需要的附加参数
参数：

options： 要请求的广告所需的附加参数。目前只有Native广告需要设置附加参数，使用AdRequestOption::newNativeBuilder()构建

NativeAdRequestOptionBuilder,并进一步构建参数选项。

返回值：AdRequest.Builder实例对象。

5.2.3 UnionAd

标识一个广告，可以通过一个AdRequest加载广告内容。在使用中我们使用的是它的子类BannerAdView(Banner), InterstitialAd(插屏广告）, NativeAd（原生广告）。、

主要接口及参数说明：

void setAdListener(AdListener adListener)

使用：设置广告事件监听器，用来监听广告加载的状态，广告是否被点击或打开等。
参数：

adListener： 广告加载监听器。

void loadAd(AdRequest adRequest)

使用：开始加载广告。
参数：

adRequest： 广告请求对象，包含着广告请求的参数

void stopLoading()

使用：停止广告加载。

5.2.4 AdListener

广告事件监听器，监听广告加载的过程和结果，比如广告加载是否成功，广告是否被点击等。

主要接口及参数说明：

void onAdLoaded(UnionAd ad)

使用：广告被成功加载。
参数：

ad： 被成功加载的广告对象。

void onAdClosed(UnionAd ad)

使用：广告被关闭。
参数：

ad： 被关闭的广告。

void onAdOpened(UnionAd ad)

使用：广告被打开。
参数：

ad： 被打开的广告。

void onAdClicked(UnionAd ad)

使用：广告被点击。
参数：

ad： 被点击的广告。

void onAdError(UnionAd ad, AdError error)

使用：广告加载出错。
参数：

ad： 广告加载出错的广告
error： 广告出错信息

5.2.5 AdError

广告出错的错误信息。包括错误码和详细的错误信息。 主要错误码如下：

错误码 对应值 含义
ERROR_CODE_NETWORK_ERROR 1000 网络错误
ERROR_CODE_NO_FILL 1001 没有匹配的广告
ERROR_CODE_INTERNAL_ERROR 1002 内部错误
ERROR_CODE_SERVER_ERROR 1003 服务器错误
ERROR_CODE_REMOTE_CLOSED 1004 远端被关闭

5.2.6 BannerAdView

条幅广告，接口描述见UnionAd。

5.2.7 InterstitialAd

插屏广告，接口描述见UnionAd，需要注意的是在onAdLoaded的时候调用其show方法。

5.2.8 NativeAd

原生广告，接口描述见UnionAd。
原生广告在被加载之后，会以NativeAdAssets的形式将原生数据返回，NativeAdAssets相关的接口见NativeAdAssets。

5.2.9 NativeAdAssets

原生广告返回的数据，包括广告的标题，详细描述，一个图标和一张封面图。图片以Image对象的形式返回，如果在请求广告的时候设置了requestExtraResource,则广告SDK会自动下载响应的图片，并以drawable的形式返回，如果没有设置，则drawable为空，可以通过Image.getUrl获取图片地址。

主要接口及参数说明：

public String getTitle()

使用：获取原生广告的标题。
返回值：原生广告的标题。

public String getDescription()

使用：获取原生广告的广告详细描述信息。
返回值：原生广告的广告详细描述信息。

public Image getIcon()

使用：获取原生广告图标。
返回值：原生广告的图标。

public Double  getRating()

使用：获取评分。
返回值：原生广告的评分信息，一般对应应用型广告。

public String getPrice()

使用：获取价格信息。
返回值：原生广告的价格信息

public Image getCover()

使用：获取原生广告的封面大图.(一个）
返回值：原生广告的封面大图。

public List<Image> getCovers()

使用：获取原生广告的封面大图信息。（多个）
返回值：原生广告的封面大图信息。

注意：getCover与getCovers都是用来获取封面图片，如果返回的只有一张封面图片，则从这两个接口可以获取同样的封面图片信息，如果返回的有多张封面图片，则getCover获取多张中的其中一张，getCovers则可以获取所有封面图片。getCovers的使用场景通常为：开发者希望展示多张封面或者自己从多张封面中决策出最符合自己展示条件的。

5.2.10 NativeAdRequestOptionBuilder

原生广告请求参数的构建类，用来方便的构建原生广告请求中除了通用广告请求参数(pub, testDeviceId)之外的其他参数。
AdRequest.Builder主要接口及参数说明：

主要接口及参数说明：

public NativeAdRequestOptionBuilder requestExtraResource(bool switcher)

使用：只用于原生广告， 设置是否需要请求大图资源，对于自定义的广告位，如果小图标和文字足够，则没有必要浪费资源去请求大图资源，则可设置此标志位为false, 默认为true.
参数：

switcher:是否请求大图资源。

public NativeAdRequestParamBuilder requestCoverImageSize(int width, int height)

使用：只用设置请求封面大图的最佳尺寸。
参数：

width:宽度,像素为单位。
height:高度,像素为单位。

6.打包发布

6.1 打包前检查

请检查是否已经按文档的步骤嵌入了广告SDK，包括AndroidManifest.xml的配置、初始化接口的调用、各个广告接口的使用以及是否正确使用对应广告类型的渠道ID。

6.2 测试

6.2.1测试注意事项

广告SDK目前支持Facebook, Google和U盟三个源的广告，并根据一定策略选择广告并返回给用户进行展示。如果要展示相应源的广告，除了在广告SDK后台需要配置之外，客户端测试设备也需要满足如下测试条件：

Google广告测试：安装最新版本google-play-service。
Facebook广告测试：安装最新版facebook并登录。

6.2.2测试方法

打开手机网络（WIFI或移动网络），并在手机上运行测试是否可以正常获取广告。
如果正确的获取到广告，则会展示如下广告内容（Native广告的展现样式依开发者自定义为准）：

1　条幅广告示例：
条幅广告示例

2　插屏广告示例：
插屏广告示例

3　原生广告示例：
原生广告示例

7.常见问题

7.1 环境配置问题

7.1.1 广告SDK使用哪种字符编码

广告SDK使用UTF-8字符编码,在嵌入广告以及导入示例程序的时候请使用UTF-8编程环境，否则会出现乱码情况。

7.1.2 广告SDK兼容Android系统SDK的哪些版本

广告Android SDK兼容Android 系统API Level 11及以上版本SDK.

7.1.3 渠道ID错误使用

如果在展示广告时，使用错误的pub id，显示的广告会异常。出现该情况时，请检查展示广告使用的pub id是否正确。例如，使用banner、插屏广告，展示广告时需要使用两个不同的pub id，以区分不同类型的广告。

7.1.4 全新安装首次启动崩溃

在部分6.0设备上，全新安装首次启动会出现启动崩溃的状况，这是Android系统的一个bug,该bug的表现是Application.onCreate未被调用，导致广告SDK核心初始化流程未被调用，从而引起崩溃。
后续版本中SDK会在内部增加对该问题的处理， 对于开发者来说，一个解决方案是在AndroidManifest.xml中将Application的allowbackup属性设置为false。
关于相关该bug的部分讨论见：
https://code.google.com/p/android-developer-preview/issues/detail?id=2965

7.2 联系我们

如果您在使用广告Android SDK 的过程中遇到了问题，或者对于SDK有任何宝贵的改进意见，欢迎联系我们的企业客服，我们将竭诚为您服务。

Back to Home page.

ucunion-logo

⚠️ **GitHub.com Fallback** ⚠️