Android SDK下载与集成

1. 概述

本手册介绍如何将OpenMediation SDK集成到您的Android应用中。

OpenMediation致力于提供多样且富有竞争力的广告变现解决方案，支持插屏、激励视频、原生、横幅和交叉推广等丰富的广告类型。OpenMediation聚合平台支持AdTiming、AdMob、Facebook、UnityAds、Vungle、Tapjoy、AppLovin、AdColony、Chartboost、Pangle、Mintegral、Helium、TencentAd 和 ironSource等国内外主流的广告网络对接，帮助开发者实现“一次接入，全部覆盖”。

2. Ads ID

在进行SDK集成之前，您需要先有一个OpenMediation Publisher前台的开发者账号，然后注册您的应用、创建广告位等操作，得到集成所必要的信息：APP_KEY 和 Placement ID。开发者前台请访问 OpenMediation Developer Platform。

APP_KEY: APP_KEY 是给开发者应用分配的唯一标识，在开发者前台创建应用后即可获取APP_KEY。

• 点击 Setup -> Select 'App Settings' -> Click on 'APP Info'
  
• 点击 'Copy'                     

Placement ID: 是广告位的唯一标识。开发者可以创建多个广告位，进入菜单 Setup ->Placements 可以查看到所有的广告位信息。 OpenMediation广告位类型支持横幅、插屏、开屏、原生、激励视频和交叉推广等多种类型。

3. 添加SDK到开发项目中

将下面的脚本添加到您的 project-level build.gradle 文件中。

allprojects {
    repositories {
        google()
        jcenter()
        maven { url 'https://dl.openmediation.com/omcenter/' }
    }
}

将下面的脚本添加到您的 application-level build.gradle 文件中 dependencies 分段内。

implementation 'com.openmediation:om-android-sdk:+'

从 GitHub 仓库下载

您可以通过 GitHub 仓库来获取 OpenMediation SDK 源码和演示应用程序：

git clone git://github.com/AdTiming/OpenMediation-Android.git

4. 更新 AndroidManifest.xml

<manifest>
    ...
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
</manifest>

5. Proguard

如果您在应用中使用了Proguard来保护代码，请务必添加下面的配置到您的 Proguard 配置文件 (Android Studio: proguard-rules.pro or Eclipse: proguard-project.txt)，否则SDK将会报错。

-dontwarn com.openmediation.sdk.**.*
-keep class com.openmediation.sdk.**{*;}

6. 重载Activity生命周期方法

在开始初始化SDK之前，您需要重写应用的生命周期方法。重载每个Activity对象的onPause()和onResume()方法，调用对应的OmAds.onPause()和onResume()方法，如下所示。

protected void onResume() {
     super.onResume();
     OmAds.onResume(this);
  } 
protected void onPause() {
     super.onPause();
     OmAds.onPause(this);
  }

7. 初始化SDK

完成SDK的下载与集成后，就可以开始对SDK进行初始化了。初始化是在调用SDK进行广告加载展示之前必须做的工作，否则SDK不会进行任何有效的工作。我们建议在应用启动的时候进行SDK初始化，比如在 Application 或 Activity 的 onCreat() 事件方法是一个不错的选择，如下所示：

import com.openmediation.sdk.InitConfiguration;
import com.openmediation.sdk.OmAds;
import com.openmediation.sdk.InitCallback;
import com.openmediation.sdk.utils.error.Error;
...

InitConfiguration configuration = new InitConfiguration.Builder()
          .appKey("Your AppKey")
          .logEnable(false)
          .build();
OmAds.init(configuration, new InitCallback() {

    // Invoked when the initialization is successful.
    @Override
    public void onSuccess() {
    }

    // Invoked when the initialization is failed.
    @Override
    public void onError(Error error) {
    }
});

最佳实践：按广告类型初始化

v2.0及以上版本的SDK提供了新的初始化方案，可以指定一个或多个广告类型进行初始化。我们建议使用这种新的方法进行初始化，因为按广告类型的初始化方法仅会获取对应类型的广告进行预加载。基于这种方法，开发者可以将不同类型广告的初始化和预加载放在应用的不同时间节点上，基于应用的广告场景设计。这种方案的好处是，可以将原先集中在应用启动的时间点进行的广告预加载动作，分散到不同时间点，避免可能的网络拥挤导致广告加载速度缓慢、以致影响应用体验。

下面代码示例了如何通过初始化方法仅初始化和预加载激励视频与插屏广告两种类型。

// Ad Units should be in the type of OmAds.AD_TYPE.AdUnitName, for example:
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.INTERSTITIAL, OmAds.AD_TYPE.REWARDED_VIDEO)
    .build();
OmAds.init(configuration, callback);

可以在应用的不同时间点分别初始化每一种广告类型，如下所示：

// Init with pre-load Rewarded video ads
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.REWARDED_VIDEO)
    .build();
OmAds.init(configuration, callback);
// Init with pre-load Interstitial
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.INTERSTITIAL)
    .build();
OmAds.init(configuration, callback);

• 如果类型不传入任何参数，意味着会默认预加载激励视频和插屏广告类型
• 如果不想要做任何预加载，请传入 OmAds.AD_TYPE.NONE 参数

// Init with no pre-load 
InitConfiguration configuration = new InitConfiguration.Builder()
    .appKey("Your AppKey")
    .preloadAdTypes(OmAds.AD_TYPE.NONE)
    .build();
OmAds.init(configuration, callback);

实现回调事件处理

OpenMediation SDK在初始化操作中会出发一系列的事件来通知应用程序，您需要实现InitCallback接口的onSuccess() 和 onError() 回调方法以处理初始化成功和失败的事件。

@Override
public void onSuccess() {
    // Add code here to process init success event.
}
@Override
public void onError(Error error) {
    // Add code here to process init failed event.
    // Parameter message tells the error information.
}

上报自定义用户标识符

应用可以通过SDK上报自定义的设备标识符，只需要在初始化之前调用setUserId方法设置。该标识符会在用户级的数据中体现。

OmAds.setUserId(String userId);

传递归因信息（可选）

如果您项目同时集成了AppsFlyer SDK，我们需要您将应用归因数据传递到OpenMediation，以便我们帮您准确计算各Media Source、Campaign层级ROAS及LTV数据。

1. 在AppsFlyer onConversionDataSuccess 回调中调用 sendAFConversionData 

AppsFlyer 5.0.0以上版本

@Override
public void onConversionDataSuccess(Map<String, Object> conversionData) {
    OmAds.sendAFConversionData(conversionData);
}

AppsFlyer 4.x 或更低版本

@Override
public void onInstallConversionDataLoaded(Map<String, String> map) { {
    OmAds.sendAFConversionData(map);
}

2. 在AppsFlyer onAppOpenAttribution 回调中调用 sendAFDeepLinkData

@Override
public void onAppOpenAttribution(Map<String, String> conversionData) {
    OmAds.sendAFDeepLinkData(conversionData);
}

8. 使用Test Suite套件测试集成（可选）

• 将以下脚本项加入到应用级的 build.gradle 文件中的 dependencies 分段内：

implementation 'com.openmediation:test-suite:+'

• 使用下面这行代码启动测试套件：

import com.openmediation.testsuite.TestSuite;
...
TestSuite.launch(activity, appKey);

您可以通过测试套件工具章节获取更多帮助。