# JgAdsSdk-Android-Demo **Repository Path**: CapRobin/jgads-sdk-android-demo ## Basic Information - **Project Name**: JgAdsSdk-Android-Demo - **Description**: 极光广告SDK，安卓demo - **Primary Language**: Android - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2022-09-30 - **Last Updated**: 2022-09-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # JgAds Android Sdk——接入文档 V1.3.2.6 目录 [TOC]
## 1. 概述 ### 1.1 概述 尊敬的开发者朋友，欢迎您使用极光Ads广告SDK。通过本文档，您可以快速完成广告SDK的集成。 **注意：本SDK仅支持中国大陆地区**；如需发布到Google Play，请勿引入本SDK及相关依赖文件。 ### 2. 支持的广告类型
类型 简介 适用场景
开屏广告 开屏广告以APP启动作为曝光时机的模板广告，需要将开屏广告视图添加到承载的广告容器中，提供5s可感知广告展示 APP启动界面常会使用开屏广告
Banner广告 Banner广告是横向贯穿整个可视页面的模板广告，需要将Banner广告视图添加到承载的广告容器中 任意界面的固定位置，不建议放在RecyclerView、List这种滚动布局中当item
信息流自渲染广告 信息流自渲染广告，可自行设计样式，以满足不同的样式需求 信息流列表，轮播控件，固定位置都是较为适合
信息流模版广告 信息流模板广告，支持上文下图、下图上文、左图右文、右图左文、纯图 信息流列表，轮播控件，固定位置都是较为适合
插屏广告 插屏广告是移动广告的一种常见形式，在应用流程中弹出，当应用展示插屏广告时，用户可以选择点击广告，访问其目标网址，也可以将其关闭并返回应用 在应用执行流程的自然停顿点，适合投放这类广告
激励视频广告 将短视频融入到APP场景当中，用户观看短视频广告后可以给予一些应用内奖励 常出现在游戏的复活、任务等位置，或者网服类APP的一些增值服务场景
## 3. Demo及SDK下载链接 > [JgAdsDemo-演示APK下载地址](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/demo/app-release.apk) > > [SDK版本更新日志](https://ssp.jiguang.cn/doc/pages/adsand/) ## 4. SDK版本说明 ## 5. SDK接入流程 ### 5.1 添加SDK到工程中 接入环境：**Android Studio**，**minSdkVersion 16** #### 5.1.1 添加仓库地址 首先需要在项目的build.gradle文件中引入如下配置： ```java allprojects { repositories { ... google() jcenter() mavenCentral() } } ``` #### 5.1.2 添加JgAdsSdk 将广告所需要的依赖集成进去 ```java dependencies { // support支持库，如果是AndroidX请使用对应的支持库 implementation 'com.android.support:appcompat-v7:28.0.0' implementation 'com.android.support:support-v4:28.0.0' implementation 'com.android.support:design:28.0.0' // 极光Ads广告SDK implementation "cn.jiguang.sdk.ad.third:jgads:1.3.2.6" } ``` #### 5.1.3 注意事项 * 支持主流架构，x86架构暂不支持 ```java ndk { // 设置支持的SO库架构，暂不支持x86 abiFilters 'armeabi-v7a', 'arm64-v8a' } ``` * 引入了Android R的 标签,需要对gradle版本进行限制，限制范围为：3.3.3、 3.4.3、 3.5.4、3.6.4、4.0.1 ，开发者根据自身情况酌情升级 ### 5.3 权限申请 使用SDK时可能需要以下权限，为了保证使用广告的正确，请在6.0及以上的手机中使用SDK前及时申请。 ```java ``` ### 5.4 兼容配置 #### 5.4.2 网络配置 需要在 AndroidManifest.xml 添加依赖声明**uses-library android:name="org.apache.http.legacy" android:required="false"**， 且 application标签中添加 **android:usesCleartextTraffic="true"**，适配网络http请求，否则 SDK可能无法正常工作，接入代码示例如下： ```java ... ... ``` #### 5.4.3 混淆配置 如果打包时开启了混淆配置，请按需添加以下混淆内容，并保证广告资源文件不被混淆 ```java -keep class com.junion.**{ *; } ``` ### 5.5 隐私信息控制开关 **为了保证您的App顺利通过检测，结合当前监管关注重点，我们可以将JgAdsSdk的初始化放在用户同意隐私政策之后。** **如合规有更高要求，可以使用以下方法进行控制，但会严重降低广告收益，可根据实际需求进行设置，或联系我发运营人员获取建议。** 同时JgAdsSDK初始化时开放以下接口，确保mac，imei等设备标识不被读取： ```java //【慎改】是否同意隐私政策，将禁用一切设备信息读起严重影响收益 .agreePrivacyStrategy(true) // 是否可获取定位数据 .isCanUseLocation(true) // 是否可获取设备信息 .isCanUsePhoneState(true) // 下载类广告提示类别，TYPE_ALL：WIFI和流量都提示、TYPE_NOT_WIFI：WIFI下不提示、TYPE_NOT_ALL：WIFI和流量都不提示 .downloadTipType(DownloadTipType.TYPE_ALL) ``` ## 6. 示例代码 ### 6.1 SDK初始化 在Application中进行SDK的初始化(详情请参考Demo) ```java // 初始化JgAds广告SDK JgAds.getInstance().init(this, new JUnionInitConfig.Builder() // 设置APPID，必须的 .appId(JgAdsDemoConstant.APP_ID) // 是否开启Debug，开启会有详细的日志信息打印 // 注意上线后请置为false .debug(BuildConfig.DEBUG) .setOAID("") // 请传入oaid 增加广告填充提高收益 .setAAID("") // 请传入aaid 增加广告填充提高收益 .setVAID("") // 请传入vaid 增加广告填充提高收益 .build()); ``` PS ：AppId通过后台配置生成，初始化必须在主线程中进行，SDK暂不支持多进程。 ### 6.2 开屏广告示例 开屏广告建议在闪屏页进行展示，开屏广告的宽度和高度取决于容器的宽高，都是会撑满广告容器；**开屏广告的高度必须大于等于屏幕高度（手机屏幕完整高度，包括状态栏之类）的75%**，否则可能会影响收益计费（广点通的开屏甚至会影响跳过按钮的回调）。 ```java // 创建开屏广告实例，第一个参数可以是Activity或Fragment，第二个参数是广告容器，第二个参数是自定义跳过按钮 SplashAd splashAd = new SplashAd(this, tvSkip); // 设置倒计时跳过时长[3000ms~5000ms] splashAd.setCountDownTime(5000); splashAd.setListener(new SplashAdListener() { @Override public void onAdTick(long millisUntilFinished) { JUnionLogUtil.d("倒计时剩余时长（单位秒）onADTick millisUntilFinished:" + millisUntilFinished); tvSkip.setText(millisUntilFinished + "/跳过"); } @Override public void onAdReceive(SplashAdInfo adInfo) { JUnionLogUtil.d("广告获取成功回调"); // 在此回调中展示广告 // 获取开屏广告视图 View view = adInfo.getSplashAdView(); flContainer.addView(view); // 渲染开屏广告 adInfo.render(); } @Override public void onAdExpose(SplashAdInfo adInfo) { JUnionLogUtil.d("广告展示回调"); } @Override public void onAdClick(SplashAdInfo adInfo) { JUnionLogUtil.d("广告点击回调"); } @Override public void onAdSkip(SplashAdInfo adInfo) { JUnionLogUtil.d("广告跳过回调"); } @Override public void onAdClose(SplashAdInfo adInfo) { JUnionLogUtil.d("广告关闭回调"); toMain(); } @Override public void onAdFailed(JUnionError error) { JUnionLogUtil.d("广告失败回调 msg : " + error.getError()); toMain(); } }); // 加载广告，第一个参数为广告位id splashAd.loadAd(JgAdsDemoConstant.SPLASH_ID); ``` ```java // 释放开屏广告对象 if (splashAd != null) { splashAd.release(); splashAd = null; } ``` > [开屏广告示例详情](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/app/src/main/java/com/jg/ads/ad/SplashAdActivity.java) ### 6.3 横幅广告示例 Banner横幅广告建议放置在 **固定位置**，而非ListView、RecyclerView、ViewPager等控件中充当Item，Banner广告支持多种尺寸比例，可在后台创建广告位时配置，Banner广告的宽度将会撑满容器，高度自适应，建议Banner广告容器高度也为自适应。 ```java // 创建横幅广告实例，第一个参数可以是Activity或Fragment，第二个参数是广告容器 BannerAd bannerAd = new BannerAd(this, flContainer); bannerAd.setListener(new BannerAdListener() { @Override public void onAdExpose(BannerAdInfo adInfo) { JUnionLogUtil.d("广告展示回调"); } @Override public void onAdClick(BannerAdInfo adInfo) { JUnionLogUtil.d("广告点击回调"); } @Override public void onAdClose(BannerAdInfo adInfo) { JUnionLogUtil.d("广告关闭回调"); } @Override public void onAdReceive(BannerAdInfo adInfo) { JUnionLogUtil.d("广告获取成功回调"); } @Override public void onAdFailed(JUnionError error) { JUnionLogUtil.d("广告失败回调 msg : " + error.getError()); } }); // 加载广告，第一个参数为广告位id bannerAd.loadAd(JgAdsDemoConstant.BANNER_ID); ``` ```java // 释放横幅广告对象 if (bannerAd != null) { bannerAd.release(); bannerAd = null; } ``` >[Banner广告示例详情](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/app/src/main/java/com/jg/ads/ad/BannerAdActivity.java) ### 6.4 信息流自渲染广告示例 信息流自渲染广告，可根据NativeExpressAdInfo返回的素材自定义样式。 **注意，信息流广告点击关闭时，开发者需要在onAdClose回调中将广告容器隐藏或移** ```java // 创建横幅广告实例，第一个参数可以是Activity或Fragment NativeAd nativeAd = new NativeAd(this); nativeAd.setListener(new NativeAdListener() { @Override public void onRenderFailed(NativeAdInfo nativeAdInfo, JUnionError error) { JUnionLogUtil.d("广告渲染失败"); } @Override public void onAdReceive(List nativeAdInfos) { JUnionLogUtil.d("广告获取成功回调"); } @Override public void onAdExpose(NativeAdInfo nativeAdInfo) { JUnionLogUtil.d("广告展示回调"); } @Override public void onAdClick(NativeAdInfo nativeAdInfo) { JUnionLogUtil.d("广告点击回调"); } @Override public void onAdClose(NativeAdInfo nativeAdInfo) { JUnionLogUtil.d("广告关闭回调"); } @Override public void onAdFailed(JUnionError error) { JUnionLogUtil.d("广告失败回调 msg : " + error.getError()); } }); // 加载广告，第一个参数为广告位id nativeAd.loadAd(JgAdsDemoConstant.NATIVE_ID); ``` NativeAdInfo信息流自渲染广告对象主要接口 ```java // NativeAdInfo对象主要接口 // 素材是否包含视频 nativeAdInfo.isVideo() // 获取素材标题 nativeAdInfo.getTitle() // 获取素材详情 nativeAdInfo.getDesc() // 获取素材图片 nativeAdInfo.getImageUrl() // 获取素材视频控件 nativeAdInfo.getMediaView(content) // 注册视图点击事件 nativeAdInfo.registerCloseView(view) // 注册视图点击事件及曝光 nativeAdInfo.registerView(viewgroup, view...) ``` NativeAdInfo信息流自渲染广告对象 ```java if (nativeAdInfo != null) { // 注册视频监听 setVideoListener(nativeAdInfo); // 判断是否为视频类广告 if (nativeAdInfo.isVideo()) { // 获取视频视图控件 View videoView = nativeAdInfo.getMediaView(flMaterialContainer); // 添加进布局 JUnionViewUtil.addAdViewToAdContainer(flMaterialContainer, videoView); } else { ImageView imageView = new ImageView(flMaterialContainer.getContext()); ViewGroup.LayoutParams imageViewLayoutParams = new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT); // 获取图片并展示 JgAds.getInstance().getImageLoader().loadImage(imageView.getContext(), nativeAdInfo.getImageUrl(), imageView); imageView.setScaleType(ImageView.ScaleType.CENTER_CROP); imageView.setLayoutParams(imageViewLayoutParams); JUnionViewUtil.addAdViewToAdContainer(flMaterialContainer, imageView); } if (tvTitle != null) { // 设置标题 tvTitle.setText(nativeAdInfo.getTitle()); } if (tvDesc != null) { // 设置正文 tvDesc.setText(nativeAdInfo.getDesc()); } if (tvAdTarget != null) { // 设置渠道 tvAdTarget.setText("极光Ads广告"); } // 注册关闭事件 nativeAdInfo.registerCloseView(ivClose); // 注册视图和点击事件 nativeAdInfo.registerView(rlAdContainer, rlAdContainer); } ``` ```java // 释放信息流自渲染广告对象 if (nativeAd != null) { nativeAd.release(); nativeAd = null; } ``` > [信息流广告示例详情](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/app/src/main/java/com/jg/ads/ad/NativeAdActivity.java) ### 6.5 信息流模版广告示例 信息流模版广告，模板样式则是返回拼装好的广告视图，开发者只需将视图添加到相应容器即可，模板样式的容器高度建议是自适应。 **注意，信息流广告点击关闭时，开发者需要在onAdClose回调中将广告容器隐藏或移** ```java int widthPixels = getResources().getDisplayMetrics().widthPixels; // 创建信息流模版广告实例，第一个参数可以是Activity或Fragment，第二个参数是JUnionAdSize，需要传入容器宽高，高度建议设置0代表自适应 NativeExpressAd nativeExpressAd = new NativeExpressAd(this, new JUnionAdSize(widthPixels, 0)); nativeExpressAd.setListener(new NativeExpressAdListener() { @Override public void onRenderFailed(NativeExpressAdInfo nativeExpressAdInfo, JUnionError error) { JUnionLogUtil.d("广告渲染失败"); } @Override public void onAdReceive(List adInfos) { JUnionLogUtil.d("广告获取成功回调"); } @Override public void onAdExpose(NativeExpressAdInfo adInfo) { JUnionLogUtil.d("广告展示回调"); } @Override public void onAdClick(NativeExpressAdInfo adInfo) { JUnionLogUtil.d("广告点击回调"); } @Override public void onAdClose(NativeExpressAdInfo adInfo) { JUnionLogUtil.d("广告关闭回调"); } @Override public void onAdFailed(JUnionError error) { JUnionLogUtil.d("广告失败回调 msg : " + error.getError()); } }); // 加载广告，第一个参数为广告位id nativeExpressAd.loadAd(JgAdsDemoConstant.NATIVE_EXPRESS_ID); ``` NativeExpressAdInfo信息流模版广告对象 ```java if (nativeExpressAdInfo != null) { // 获取广告视图 View view = nativeExpressAdInfo.getNativeExpressAdView(); // 将广告视图添加到容器中 ((ViewGroup) itemView).addView(view, new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT)); // 渲染广告，一定要最后渲染 nativeExpressAdInfo.render(); } ``` ```java // 释放信息流模版广告对象 if (nativeExpressAd != null) { nativeExpressAd.release(); nativeExpressAd = null; } ``` > [信息流广告示例详情](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/app/src/main/java/com/jg/ads/ad/NativeExpressAdActivity.java) ### 6.6 插屏广告示例 插屏广告是移动广告的一种常见形式，在应用流程中弹出，当应用展示插屏广告时，用户可以选择点击广告，也可以将其关闭并返回应用。 ```java // 创建横幅广告实例，第一个参数可以是Activity或Fragment InterstitialAd interstitialAd = new InterstitialAd(this); interstitialAd.setListener(new InterstitialAdListener() { @Override public void onAdReceive(InterstitialAdInfo adInfo) { JUnionLogUtil.d("广告获取成功回调"); if (adInfo != null) { // 展示插屏广告 adInfo.showInterstitial(InterstitialAdActivity.this); } } @Override public void onAdExpose(InterstitialAdInfo adInfo) { JUnionLogUtil.d("广告展示回调"); } @Override public void onAdClick(InterstitialAdInfo adInfo) { JUnionLogUtil.d("广告点击回调"); } @Override public void onAdClose(InterstitialAdInfo adInfo) { JUnionLogUtil.d("广告关闭回调"); } @Override public void onAdFailed(JUnionError error) { JUnionLogUtil.d("广告失败回调 msg : " + error.getError()); } @Override public void onVideoStart(InterstitialAdInfo interstitialAdInfo) { JUnionLogUtil.d("视频开始播放"); } @Override public void onVideoFinish(InterstitialAdInfo interstitialAdInfo) { JUnionLogUtil.d("视频播放完毕"); } @Override public void onVideoPause(InterstitialAdInfo interstitialAdInfo) { JUnionLogUtil.d("视频暂停"); } @Override public void onVideoError(InterstitialAdInfo interstitialAdInfo) { JUnionLogUtil.d("视频错误"); } }); // 加载广告，第一个参数为广告位id interstitialAd.loadAd(JgAdsDemoConstant.INTERSTITIAL_ID); ``` ```java // 释放插屏广告对象 if (interstitialAd != null) { interstitialAd.release(); interstitialAd = null; } ``` > [插屏广告示例详情](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/app/src/main/java/com/jg/ads/ad/InterstitialAdActivity.java) ### 6.7 激励视频广告示例 将短视频融入到APP场景当中，用户观看短视频广告后可以给予一些应用内奖励。 ```java // 创建横幅广告实例，第一个参数可以是Activity或Fragment RewardAd rewardAd = new RewardAd(this); rewardAd.setListener(new RewardAdListener() { @Override public void onAdReceive(RewardAdInfo rewardAdInfo) { JUnionLogUtil.d("广告获取成功回调"); // 广告展示 rewardAdInfo.showRewardAd(RewardAdActivity.this); } @Override public void onAdReward(RewardAdInfo rewardAdInfo) { JUnionLogUtil.d("广告奖励回调"); } @Override public void onAdExpose(RewardAdInfo rewardAdInfo) { JUnionLogUtil.d("广告展示回调"); } @Override public void onAdClick(RewardAdInfo rewardAdInfo) { JUnionLogUtil.d("广告点击回调"); } @Override public void onAdClose(RewardAdInfo rewardAdInfo) { JUnionLogUtil.d("广告关闭回调"); } @Override public void onVideoCompleted(RewardAdInfo rewardAdInfo) { JUnionLogUtil.d("广频播放完毕回调"); } @Override public void onVideoSkip(RewardAdInfo rewardAdInfo) { JUnionLogUtil.d("视频跳过回调"); } @Override public void onVideoError(RewardAdInfo rewardAdInfo, String msg) { JUnionLogUtil.d("视频播放错误回调"); } @Override public void onAdFailed(JUnionError error) { JUnionLogUtil.d("视频错误"); } }); rewardAd.loadAd(adPosition); // 加载广告，第一个参数为广告位id rewardAd.loadAd(JgAdsDemoConstant.REWARD_ID); ``` ```java // 释放激励广告对象 if (rewardAd != null) { rewardAd.release(); rewardAd = null; } ``` > [插屏广告示例详情](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/app/src/main/java/com/jg/ads/ad/RewardAdActivity.java) ### 6.8 备注 具体的接入代码和流程，请参考Demo ## 7. 广告竞价 极光Ads开屏、信息流、插屏、激励视频支持广告竞价功能，可以参考demo进行对接 以开屏广告为例： 1.在每次loadAd时，都会在onAdReceive回调中会返回splashAdInfo广告对象，广告对象中会存放广告素材和价格信息 ```java // 获取广告价格（分） splashAdInfo.getBidPrice(); ``` 2.获取到价格后可参与比价，比价成功后请先调用竞赢上报，否则广告将无法使用 ```java /** * 媒体回传竞价队列的二价ecpm，竞价成功后，必须在展示前回传递 * 注：若当前竞价队列中只存在极光Ads一个渠道，则竞赢上报的价格为当前AdInfo对象的底价，如：splashAdInfo.getBidFloor()，价格（分） * price 竞赢价格（分） */ splashAdInfo.sendWinNotice(int price); ``` 3.如果失败，或其他情况，请调用竞败上报 ```java /** * price 三方竞赢价格（分） * msg 失败原因 LOW_PRICE竞价失败、OTHER其他 */ splashAdInfo.sendLossNotice(Integer.valueOf(price), BidLossNotice.LOW_PRICE); ``` 4.展示广告 > [例：模板信息流广告竞价示例详情](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/app/src/main/java/com/jg/ads/ad/NativeBidExpressAdActivity.java) ## 8. 常见问题和错误调试 > [常见问题和错误调试及错误码](https://gitee.com/jiguang-official/jgads-sdk-android-demo/blob/master/ErrorCode/JgAdsErrorCode.md) ## 9.商务合作 邮箱 : marketing@jiguang.cn