Android_flutter

Android 集成指南

更新日志

版本	修订日期	修订说明
v2.5.02	2025-10-21	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压缩包解压后，把admaosdk文件夹复制到工程目录下
b、导入flutter插件

dependencies:
  adsjmsdk:
    path: admaosdk

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

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


depedencies {
   compileOnly(name: 'maosdk_x.x.x', ext: 'aar')
   compileOnly(name: 'maosdk_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" />

注意: SDK不强制获取以上权限，即使没有获取可选权限SDK也能正常运行；获取以上权限将帮助优化投放广告精准度和用户的交互体验，提高eCPM

1.2.2 运行环境配置

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

如果开发者声明 targetSdkVersion 到 API23 以上，请确保调用本SDK的任何接口前，已经申请到了SDK要求的所有权限，否则SDK部分特性可能受限。
建议 targetSdkVersion 不大于 28

1.3 其他配置

1.3.1 注意

在工程的 MainActivity 的 configureFlutterEngine 周期中注册AdMaosdkPlugin插件，如

 import androidx.annotation.NonNull;
 import com.mao.plugin.adsjmsdk.AdMaosdkPlugin;
 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 AdMaosdkPlugin());
 }

}

1.4 初始化SDK

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

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

        MaoSdk.init(this, "应用ID");
    }
}

如果工程中没有application相关的类，可以新建个application并继承FlutterApplication

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加载开屏广告方式一

              SjmAdSdk.showSplashAd(
                    adId,
                    5,
                    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 错误 " + message);
                    },
                  );

2.1.2 回调说明

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

    /**
     * 开屏广告展示
     */
    void onSjmAdShow();
    /**
     * 点击
     */
    void onSjmAdClicked();
    /**
     * 开屏广告关闭
     */
    void onSjmAdClosed();
    /**
     * 广告错误
     */
    void onSjmAdError(SjmAdError error);

2.1.3 加载开屏广告方式二

    SjmSplashAd splashAd = new SjmSplashAd(this, this, "广告位id", 超时时长（int型，单位秒）);

    splashAd.fetchAndShowIn(container);

改方式是通过原生方式加载广告具体示例详见 Demo 中的 SplashActivity
不要在SplashActivity#onCreate()生命周期内直接创建SjmSplashAd对象，创建SjmSplashAd对象需要延时

2.1.4 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为接入方提供激励视频广告，该广告的效果为观看完毕视频广告，发放奖励给用户。使用场景包括但不限于：

1.游戏等应用内观看视频广告获得游戏内金币等：用户必须观看完整视频才能获取奖励；
2.积分类应用接入；

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();

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

本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);

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

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();

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

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();

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

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);

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

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'

添加权限

您项目中的targetSdkVersion大于等于30时需要在AndroidManifest加入下面配置

 <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
   /**
     * 广告加载失败或错误
     */

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

6 常见问题

1. support-v4 包依赖

为了适配下载和安装相关功能，确保support-v4包的版本为24.2.0及以上版本。

2. 权限申请与开屏广告

请在APP的权限申请结束回调后，再创建SjmSplashAd对象，避免获取container失败而导致的crash。

3. 接入过程中测试接口

将工程的applicationId修改为 demo 工程的applicationId，并使用demo中的广告位id进行测试。

4. 电话权限、定位权限与外部存储权限申请

SDK不强制获取以上权限，即使没有获取可选权限SDK也能正常运行；获取以上权限将帮助优化投放广告精准度和用户的交互体验，提高eCPM。

5. 开屏广告加载失败或闪退

开屏广告SjmSplashAd对象不可以在应用的SplashActivity#onCreate生命周期内直接创建，需要延时1000ms左右再进行new操作，参考代码

  ViewGroup container = (ViewGroup) this.findViewById(R.id.splash_container);
  container.postDelayed(()->{
          SjmSplashAd SjmSplashAd = new SjmSplashAd(this, this, pos_id, 3);
      }, 1000);

提示"开屏广告容器的高度低于400dp"时，需要修改容器的高度大于设备屏幕高度的75%

6. 出现错误 java.lang.ClassNotFoundException: Didn't find class "com.kwad.sdk.api.SdkConfig$Builder

检查build.gradle中是否依赖了Sjm_kssdk.aar

7. 开屏广告显示不完整

如果使用页面的根节点，或 include layout 的根节点作为开屏广告的容器，会出现显示不完整的情况，需要将开屏广告的容器设置为非根节点的 ViewGroup

8. 激励视频显示黑屏

需要在AndroidManifest.xml的<Application>标签下配置android:hardwareAccelerated="true"来开启硬件加速

9. 视频列表内容页加载崩溃

检查 support-v4 是否依赖

10. 报错 java.lang.NoSuchFieldException: No field mMaxHeight in class Landroid/widget/ImageView;

需要将工程的 targetSdkVersion 降为28或以下

11. H5任务页无法获取到任务

确认调用 SjmH5AD 时传入的 SjmUser.deviceId 正确传入
调用 SjmH5AD 时传入的 SjmUser.userName 如有特殊字符，需要进行 urlEncode 处理

12. 激励视频播放时报错 android.content.res.Resources&NotFoundException: String resource ID #0x0

AndroidManifest 中 Application 标签下的 android:label 不能为字符串，需要使用 @string/ 引用