Android 集成指南


更新日志

版本 修订日期 修订说明
v2.4.11 2024-10-24 1.第三方广告网络SDK更新 2.优化双11预算

1 SDK 接入

1.1 SDK 资源导入

1.1.1 申请应用的 AppID

接入集成可使用以下测试id:

第一组测试id(建议使用) 第二组测试id(填充或不足)
应用id test0001 应用id 743p10001095
开屏广告 sjmad_test002 开屏广告 743d10003212
激励视频 sjmad_test001 激励视频 743d10003212
插屏(半屏) sjmad_test004 插屏(半屏) 743d10003213
信息流 sjmad_test005 信息流 743d10003215
banner(横幅) sjmad_test003 banner(横幅) 743d10003216
全屏视频 sjmad_test006 全屏视频 743p10001095
开发者自渲染 sjmad_test007 开发者自渲染 743d10003217
全屏竖版视频流 sjmad_test008 全屏竖版视频流
短视频内容 sjmad_test012 短视频内容 743d10003218
其他 沟通索取
如需要正式的应用id和广告位id,可自行注册账户,创建应用和广告位。
账号注册及应用与广告位创建

如对接上有任何技术或运营规则问题可以联系相关人员,微信:hzmaoyan,QQ:2538932178

1.1.2 导入 aar 及 SDK 依赖的 jar 包

a、将本SDK压缩包解压后,把adsjmsdk_safe文件夹复制到工程目录下
b、导入flutter插件

dependencies:
  adsjmsdk:
    path: adsjmsdk_safe

c、参照 example 将android/app/libs目录下的sjm_sdk_x.x.x.aar、sjm_kssdk_x.x.x.aar包复制到工程module对应的 libs 目录下, 并将以下代码添加到您Application Module的build.gradle中

dependencies:
  repositories {
    flatDir {
        dirs 'libs'
    }
}


depedencies {
   compileOnly(name: 'sjmsdk_x.x.x', ext: 'aar')
   compileOnly(name: 'sjmsdk_kssdk-ct-x.x.x', ext: 'aar')

}

1.2 AndroidManifest 配置

1.2.1 添加权限

若您的 targetSDKVersion>=23 ,您还需要在运行时进行动态权限申请(可参考示例工程)

    <uses-permission android:name="android.permission.VIBRATE" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.INTERNET" />

    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

    <!-- 安装APK权限-->
    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />

    <uses-permission android:name="android.permission.GET_TASKS" /> <!-- 如果有视频相关的广告且使用textureView播放,请务必添加,否则黑屏 -->


    <uses-permission android:name="android.permission.WAKE_LOCK" />
1.2.2 运行环境配置

本SDK可运行于 Android5.0 (API Level 21) 及以上版本,请确保build.gradle中的minSdkVersion参数不小于21

1.3 其他配置

1.3.1 注意
 import androidx.annotation.NonNull;
 import com.sjm.plugin.adsjmsdk.AdSjmsdkPlugin;
 import io.flutter.embedding.android.FlutterActivity;
 import io.flutter.embedding.engine.FlutterEngine;

 public class MainActivity extends FlutterActivity {


 @Override
 public void configureFlutterEngine(@NonNull FlutterEngine  flutterEngine) {
    super.configureFlutterEngine(flutterEngine);
    flutterEngine.getPlugins().add(new AdSjmsdkPlugin());
 }

}

1.4 初始化SDK

sdk初始化方式一:开发者需要在Application#onCreate方法中调用以下代码来初始化sdk。 目前sdk已支持多进程,如果明确某个进程不会使用到广告sdk,可以只针对特定进程初始化广告sdk。

public class MainApplication extends Application {
    @Override
    public void onCreate(){
        super.onCreate();

        SjmSdk.init(this, "应用ID");
    }
} 
void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {

    SjmAdSdk.init("test0001");
    
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        primarySwatch: Colors.grey,
        visualDensity: VisualDensity.adaptivePlatformDensity,
        buttonTheme: ButtonThemeData(minWidth: 200),
      ),

sdk初始化方式二:在调用flutter插件接口, SjmAdSdk.init("媒体ID");

2 加载广告

2.1 接入开屏广告 (SjmSplashAd)

2.1.1 原生环境接入开屏广告 (SjmSplashAd)

SDK为接入方提供了开屏广告,开屏广告建议为用户在进入App时展示的全屏广告。开屏广告为一个 View ,需要传入一个承载容器 ViewGroup ,宽高默认为 match_parent ,注意开屏广告容器 ViewGroup :width >=70% 屏幕宽,height >=80% 屏幕高,否则会影响计费

2.1.2 SjmSplashAd 广告说明
public class SjmSplashAd {

    /**
     * @param activity 
     * @param adListener
     * @param posId 广告位id
     * @param fetchTimeOut 广告时长
     */
    public SjmSplashAd(Activity activity, SjmSplashAdListener adListener, String posId, int fetchTimeOut)
    
    /**
     * 设置开屏广告事件
     */
    public void setAdListener(SjmSplashAdListener adListener);

    public void fetchAndShowIn(ViewGroup adContainer);

}
2.1.3 SjmSplashAdListener 说明
public interface SjmSplashAdListener {

    /**
     * 加载成功
     */
    void onSjmAdLoaded();

    /**
     * 拉取广告超时
     */
    void onSjmAdLoadTimeOut();

    /**
     * 开屏广告展示
     */
    void onSjmAdShow();

    /**
     * 点击
     */
    void onSjmAdClicked();


    /**
     * 倒计时结束
     */
    void onSjmAdTickOver();

    /**
     * 开屏广告关闭
     */
    void onSjmAdDismissed();

    /**
     * 广告错误
     */
    void onSjmAdError(SjmAdError error);
}
2.1.4 加载开屏广告
    SjmSplashAd splashAd = new SjmSplashAd(this, this, "广告位id", 超时时长(int型,单位秒));

    splashAd.fetchAndShowIn(container);
2.1.5 flutter插件开屏广告加载
            SplashAdView(
              adId: "sjmad_test009",//sjmad_test009 sjmad_test002
              width: width,
              height: height,
              onSjmAdLoaded: (String id) {
                print("SplashAd 加载成功");
              },
              onSjmAdShow: (String id) {
                print("SplashAd 开屏展示");
              },
              onSjmAdClicked: (String id) {
                print("SplashAd 开屏点击");
              },
              onSjmAdClosed: (String id) {
                print("SplashAd 开屏关闭");
              },
              onSjmAdError: (String id, int code, String message) {
                print("SplashAd 加载失败");
              }

2.2 接入激励视频 (SjmRewardVideoAd)

本SDK为接入方提供激励视频广告,该广告的效果为观看完毕视频广告,发放奖励给用户。使用场景包括但不限于:

2.2.1 SjmRewardVideoAd 广告说明
SjmAdSdk.showRewardVideoAd(
                    "广告位id",
                    onSjmAdTradeId:(String id){
                      print("RewardVideoAd onSjmAdTradeId");
                    },
                    onSjmAdLoaded: (String id) {
                      print("RewardVideoAd onSjmAdLoad");
                    },
                    onSjmAdShow: (String id) {
                      print("RewardVideoAd onSjmAdShow");
                    },
                    onSjmAdReward: (String id) {
                      print("RewardVideoAd onReward");
                    },
                    onSjmAdClicked: (String id) {
                      print("RewardVideoAd onSjmAdClick");
                    },
                    onSjmAdVideoComplete: (String id) {
                      print("RewardVideoAd onVideoComplete");
                    },
                    onSjmAdClosed: (String id) {
                      print("RewardVideoAd onSjmAdClose");
                    },
                    onSjmAdError: (String id, int code, String message) {
                      print("RewardVideoAd onSjmAdError");
                    },
                  );
2.2.2 SjmRewardVideoAdListener 说明
public interface SjmRewardVideoAdListener{
    /**
     * 每次广告加载成功,会在此回调生生成一个唯一的tradeid
     */
    void onSjmAdTradeId(String tradeid, String tradeKey, String isVerify);

    /**
     * 视频素材缓存成功,可在此回调后进行广告展示
     */
    void onSjmAdLoaded(String adid);

    /**
     * 视频素材缓存成功,可在此回调后进行广告展示
     */
    void onSjmAdVideoCached();

    /**
     * 激励视频广告页面展示
     */
    void onSjmAdShow();

    /**
     * 广告展示出错
     */
    void onSjmAdShowError(SjmAdError adError);

    /**
     * 激励视频广告被点击
     */
    void onSjmAdClick();

    /**
     * 激励视频播放完毕
     */
    void onSjmAdVideoComplete();

    /**
     * 激励视频广告曝光
     */
    void onSjmAdExpose();

    /**
     * 激励视频触发激励(观看视频大于一定时长或者视频播放完毕)
     */
    void onSjmAdReward(String adid) ;

    /**
     * 激励视频广告被关闭
     */
    void onSjmAdClose() ;

    /**
     * 广告流程出错
     */
    void onSjmAdError(SjmAdError adError) ;
}

加载广告具体示例详见 Demo 中的reward_video.dart, AdsjmsdkPlugin
原生代码调用可以参考android原生文档和demo中的sjm_ad.dart

2.3 接入插屏广告 (SjmInterstitialAd)

本SDK为接入方提供个性化模板插屏广告,开发者不用自行对广告样式进行编辑和渲染,可直接调用相关接口获取广告 view,广告样式模板以及微调后期支持开发者编辑。

2.3.1 SjmInterstitialAd 广告说明
SjmAdSdk.loadInterstitalAd(
                    "广告位id",
                    onSjmAdLoaded: (String id) {
                      print("InterstitalAd onSjmAdLoad");
                    },
                    onSjmAdShow: (String id) {
                      print("InterstitalAd onSjmAdShow");
                    },
                    onSjmAdClicked: (String id) {
                      print("InterstitalAd onSjmAdClick");
                    },
                    onSjmAdClosed: (String id) {
                      print("InterstitalAd onSjmAdClose");
                    },
                    onSjmAdError: (String id, int code, String message) {
                      print("InterstitalAd onSjmAdError");
                    },
                  );
2.3.2 SjmInterstitialAdListener 说明
    void onSjmAdLoaded();

    void onSjmAdShow();

    void onSjmAdClicked();

    void onSjmAdError(SjmAdError adError);

    void onSjmAdClosed();

2.4 接入Banner广告 (SjmBannerAd)

本SDK为接入方提供个性化模板 Banner 广告,开发者不用自行对广告样式进行编辑和渲染, Banner 广告为一个 View,需要传入一个承载容器 ViewGroup,广告样式模板以及微调后期支持开发者编辑。

2.4.1 SjmBannerAd 广告说明
BannerAdView是一个Widget,使用方法如下:
BannerAdView(
              adId: "广告位id",
              width: 400,
              height: 60,
              onSjmAdLoaded: (String id) {
                print("BannerAd onSjmAdLoad");
              },
              onSjmAdShow: (String id) {
                print("BannerAd onSjmAdShow");
              },
              onSjmAdClicked: (String id) {
                print("BannerAd onSjmAdClick");
              },
              onSjmAdClosed: (String id) {
                print("BannerAd onSjmAdClose");
              },
              onSjmAdError: (String id, int code, String message) {
                print("BannerAd onError");
              },
            )
2.4.2 SjmBannerAdListener 说明
    void onSjmAdLoaded();

    void onSjmAdShow();

    void onSjmAdClicked();

    void onSjmAdClosed();

    void onSjmAdError(SjmAdError var1);

2.5 接入全屏视频广告 (SjmFullScreenVideoAd)

本SDK为接入方提供全屏视频广告

2.5.1 SjmFullScreenVideoAd 广告说明
SjmAdSdk.showFullVideoAd(
                    "sjmad_test006",
                    onSjmAdLoaded: (String id) {
                      print("RewardVideoAd onSjmAdLoad");
                    },
                    onSjmAdShow: (String id) {
                      print("RewardVideoAd onSjmAdShow");
                    },
                    onSjmAdClicked: (String id) {
                      print("RewardVideoAd onSjmAdClick");
                    },
                    onSjmAdVideoComplete: (String id) {
                      print("RewardVideoAd onVideoComplete");
                    },
                    onSjmAdClosed: (String id) {
                      print("RewardVideoAd onSjmAdClose");
                    },
                    onSjmAdError: (String id, int code, String message) {
                      print("RewardVideoAd onSjmAdError");
                    },
                  );
2.5.2 SjmFullScreenVideoAdListener 说明

    void onSjmAdLoaded();

    void onSjmAdShow();

    void onSjmAdClicked();

    void onSjmAdError(SjmAdError adError);

    void onSjmAdVideoCached();

    void onSjmAdClosed();

    void onSjmAdVideoComplete();

2.6 接入原生模版信息流广告 (SjmNativeExpressAd)

本SDK为接入方提供原生模版信息流广告。

2.6.1 SjmNativeExpressAd 广告说明
NativeExpressAdView是一个Widget,使用方法如下:

NativeExpressAdView(
              adId:  "广告位id",
              width: 350,
              height: 300,
              onSjmAdLoaded: (String id) {
                print("native_express onSjmAdLoad");
              },

              onSjmAdShow: (String id) {
                print("native_express onSjmAdShow");
              },
              onSjmAdClicked: (String id) {
                print("native_express onSjmAdClick");
              },
              onSjmAdClosed: (String id) {
                print("native_express onSjmAdClose");
              },
              onSjmAdError: (String id, int code, String message) {
                print("native_express onError");
              },
            )
2.6.2 SjmNativeExpressAdListener 说明
    void onSjmAdLoaded();
    void onSjmAdShow();
    void onSjmAdClicked();
    void onSjmAdError(SjmAdError adError);
    void onSjmAdClosed();

3 接入H5内容页

3.1 接入H5内容 (SjmH5Ad)

SDK为接入方提供了定制H5内容页:游戏,测试,积分消耗...

3.1.1 SjmH5Ad、SjmUser说明
 SjmAdSdk.loadH5contentAd(
                    "广告位id","userid","username","userhead",
                    onIntegralNotEnough: (String id){
                      print("H5ContentPage onIntegralNotEnough");
                    },
                    onFinishTasks: (String id){
                      print("H5ContentPage onFinishTasks");
                    },
                    onGameExit: (String id){
                      print("H5ContentPage onGameExit");
                    },
                    onIntegralExpend: (String id){
                      print("H5ContentPage onIntegralExpend");
                    },
                    onSjmAdReward: (String id){
                      print("H5ContentPage onSjmAdReward");
                    },
                    onSjmAdRewardFinish: (String id){
                      print("H5ContentPage onSjmAdRewardFinish");
                    },
                    onSjmAdTradeId: (String id){
                      print("H5ContentPage onSjmAdTradeId");
                    },
                    onSjmUserBehavior: (String id){
                      print("H5ContentPage onSjmUserBehavior");
                    },

                    onSjmAdClick: (String id){
                      print("H5ContentPage onSjmAdClick");
                      },
                    onSjmAdLoaded: (String id){
                      print("H5ContentPage onSjmAdLoaded");
                    },
                    onSjmAdError: (String id, int code, String message) {
                      print("H5ContentPage onSjmAdError");
                    },
                  );
3.1.2 回调说明
    /**
     * 积分不够
     */
    void onIntegralNotEnough(SjmUser user, int needIntegral);
    /**
     * 积分消耗
     *  expendIntegral>0,用户消耗了多少积分
     *  expendIntegral<0,用户任务完成领取了多少积分
     */
    void onIntegralExpend(SjmUser user, int expendIntegral);
    /**
     * 返回的是完成的任务总数
     */
    void onFinishTasks(SjmUser user, int finishTasks);
    /**
     * 退出H5
     */
    void onGameExit(SjmUser user);
    /**
     * 看广告奖励触发,此接口是完成总任务数返回的奖励接口
     */
    void onSjmAdReward(SjmUser user, int rewardIntegral);
    /**
     * h5页面中激励视频触发激励(观看视频大于一定时长或者视频播放完毕)
     */
    void onSjmAdReward(String adId);
    /**
     * h5页面中观看激励视频时视频加载成功的返回事件
     */
    void onSjmAdLoaded(String adId);
    /**
     * 每次广告加载成功,会在此回调生成一个唯一的广告id
     */
    void onSjmAdTradeId(String trade_id);
    /**
     * h5页面中观看激励视频时的点击广告的返回事件
     */
    void onSjmAdClick();
    /**
     * 用户页面的行为操作
     *  joinLottery --> 参与抽奖
     *  joinSurvey --> 参与测一测
     *  joinGuessingIdioms --> 参与猜成语
     *  stay60s --> 咨询浏览超过60s的回调
     *  joinGame --> 参与游戏
     *  taskSignIn --> 签到成功
     */
    void onSjmUserBehavior(String behavior);

4 接入语音红包

SDK为接入方提供了定制语音红包,需要引入以下库

implementation(name: 'sjm_voice_ad_4.6.0.0.aar', ext: 'aar')
implementation 'com.squareup.retrofit2:retrofit:2.2.0'
implementation 'com.squareup.retrofit2:converter-gson:2.2.0'
implementation 'com.google.code.gson:gson:2.8.5'
implementation 'com.github.bumptech.glide:glide:4.9.0'
implementation 'com.liulishuo.filedownloader:library:1.7.7'
// 版本需要指定 2.15.1
implementation ('com.google.android.exoplayer:exoplayer-core:2.15.1') {
    exclude group: "androidx.annotation", module: "annotation"
}
// 版本需要指定 2.15.1
implementation ('com.google.android.exoplayer:exoplayer-hls:2.15.1') {
    exclude group: "androidx.annotation", module: "annotation"
}
//如果您的项目中没有用到约束布局,需要添加该依赖
implementation 'com.android.support.constraint:constraint-layout:2.0.4'

添加权限

 <queries>
        <intent>
            <action android:name="android.intent.action.MAIN" />
        </intent>
        <!-- google -->
        <package android:name="com.google.android.gms" />
        <package android:name="com.android.vending" />
        <!-- freeme -->
        <package android:name="com.android.creator" />
        <!-- zte -->
        <package android:name="com.mdid.msa" />
        <!-- samsung -->
        <package android:name="com.samsung.android.deviceidservice" />
        <!-- coolpad -->
        <package android:name="com.coolpad.deviceidsupport" />
        <!-- oppo -->
        <package android:name="com.heytap.openid" />
        <!-- huawei -->
        <package android:name="com.huawei.hwid" />
        <package android:name="com.huawei.hwid.tv" />
        <package android:name="com.huawei.hms" />
        <!-- asus -->
        <package android:name="com.asus.msa.SupplementaryDID" />
        <!-- lenovo -->
        <package android:name="com.zui.deviceidservice" />
    </queries>

4.1.1 SjmVoliceAd
SjmAdSdk.loadVoliceAd(
                    "广告位id",
                    "用户id","奖励名称",
                    onSjmAdLoad: (String id) {
                      print("VoliceAd onSjmAdLoad");
                    },
                    onSjmAdShow: (String id) {
                      print("VoliceAd onSjmAdShow");
                    },
                    onSjmAdSuccess: (int reward,int stepNum) {
                      print("VoliceAd onSjmAdSuccess");
                    },
                    onSjmAdClose: (String id) {
                      print("VoliceAd onSjmAdClose");
                    },onSjmVoiceComplete: (String id) {
                    print("VoliceAd onSjmVoiceComplete");
                  },
                    onSjmAdError: (String id, int code, String message) {
                      print("VoliceAd onSjmAdError");
                    },
                  );

4.1.2 回调说明
   onSjmAdLoad: 
    /**
     * 广告加载成功
     */
   onSjmAdShow
   /**
     * 广告显示
     */
   onSjmAdSucces (int reward,int stepNum)
   /**
     * 广告奖励发放分一阶奖励和二阶奖励
     stepNum是1是第一阶,2是第二阶
     reward是每阶的奖励数据
     */
   onSjmAdClose
   /**
     * 广告关闭
     */
   onSjmVoiceComplete
   /**
     * 广告完成
     */
   onSjmAdError
   /**
     * 广告加载失败或错误
     */

6 常见问题

1. support-v4 包依赖
2. 权限申请与开屏广告
3. 接入过程中测试接口
4. 电话权限、定位权限与外部存储权限申请
5. 开屏广告加载失败或闪退
6. 出现错误 java.lang.ClassNotFoundException: Didn't find class "com.kwad.sdk.api.SdkConfig$Builder
7. 开屏广告显示不完整
8. 激励视频显示黑屏
9. 视频列表内容页加载崩溃
10. 报错 java.lang.NoSuchFieldException: No field mMaxHeight in class Landroid/widget/ImageView;
11. H5任务页无法获取到任务
12. 激励视频播放时报错 android.content.res.Resources&NotFoundException: String resource ID #0x0

1 SDK 接入

1.1 SDK 资源导入

1.2 AndroidManifest 配置

1.3 其他配置

2 加载广告

2.1 接入开屏广告 (SjmSplashAd)

2.2 接入激励视频 (SjmRewardVideoAd)

2.3 接入插屏广告 (SjmInterstitialAd)

2.4 接入Banner广告 (SjmBannerAd)

2.5 接入全屏视频广告 (SjmFullScreenVideoAd)

2.6 接入原生模版信息流广告 (SjmNativeExpressAd)

3 接入H5内容页

3.1 接入H5内容 (SjmH5Ad)