congyunxu

Transcription

1 mobisage_android_sdk [ 使用说明 ] SDK Version: mobisage_android_sdk_

2 目录 1. SDK 主要功能指南 导入 SDK 配置 AndroidManifest.xml 申请及设置 Publish ID 申请 slottoken 横幅广告 信息流广告 插屏广告 开屏广告 用户统计 使用建议

3 1. SDK 主要功能指南 1.1 导入 SDK 访问 下载 SDK 包, 解压后找到 mobisagesdk.jar 请按照如下步骤在工程的 Java Build Path 中引入 mobisagesdk.jar: 方法一 :Eclipse ADT 17 以下版本,Eclipse 右键点击工程根目录, 选择 Properties -> Java Build Path -> Libraries, 然后点击 Add External JARs... 选择指向 jar 的路径, 点击 OK, 即导入成功方法二 :Eclipse ADT 17 及以上版本用户, 请在工程目录下建一个文件夹 libs, 把 jar 包直接拷贝到这个文件夹下, 再在 >Eclipse 里面刷新一下工程就好了 详情请参考 配置 AndroidManifest.xml 在工程的 AndroidManifest.xml 中 <manifest> 区域配置 Android 权限信息, 如下所示 : <manifest > <application > <activity /> <!-- 广告点击后, 打开 Landing Site 时使用的 Activity, 必选 --> <activity android:name="com.mobisage.android.mobisageactivity" android:configchanges="keyboardhidden orientation screensize" > </activity> <!-- 应用发布渠道, 可选 --> <meta-data android:name="mobisage_channel" android:value="your channel"/> </application> <!-- sdk 所需的用户权限, 必选 --> <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"/> 3

4 <uses-permission android:name="android.permission.write_external_storage"/> <uses-permission android:name="android.permission.access_fine_location" /> <uses-permission android:name="android.permission.access_coarse_location" /> <uses-permission android:name="android.permission.access_wifi_state"/> </manifest> 如果你需要在机锋应用市场发布, 请将渠道标识 your channel 更改为 gfan 注意, 错误的渠道标识可能会影响到市场的发布, 请正确填写 1.3 申请及设置 Publish ID 申请 Publish ID 访问 注册用户并创建 App, 将获取到每个 App 的 Publish ID, 一个应用程序可以嵌入多种形式的广告, 但需要使用同一个 Publish ID; 一个 Publish ID 只能绑定一个应用程序 ; 如需发布多个程序, 请分别获取各自的 PublishID 如下图所示 : 设置 Publish ID 和状态标示字段 状状态标识字段是为了标识不同渠道不同版本的不同审核状态而设置的 您可以通过 SDK 为不同渠道不同版本的 APP 传入唯一的状态标识字段, 并且在官网平台上设置不同的状态 开发者在平台上登陆并且创建 InApp 后, 可以在我的 InApp 界面点击 设置状态标识 进入编辑状态标识字段界面 建议格式为 : 系统 _ 渠道 _ 版本号, 例如 "AnZhi_v " 字段为选填字段, 但为了最大限度保证您的应用 4

5 通过商店的审核请您尽量填写, 并谨慎更改相应的状态! 在应用的启动 Activity 或 Application 的 oncreate 方法中设置 PublishID 和状态标示字段 状态标示字段为选填项, 务必保证设置 PublishID 操作在创建广告之前 ( 例如开屏广告 ) 如下图所示 : protected void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); MobiSageManager.getInstance().initMobiSageManager(this, "raytfsi5ileduiv3kg==", " AnZhi_v "); 1.4 申请 slottoken 申请 PublishID 后, 需为要展示的广告类型申请 slottoken, 如需展示 banner, 需申请 banner 的 slottoken, 该 slottoken 只能创建 banner 类型的广告位. 一个 slottoken 可以创建多个相同类型广 告位. 1.5 横幅广告 创建广告 在应用的显示广告 Activity 的 layout 文件对应位置添加如下 xml 代码 : 5

6 <LinearLayout android:layout_centerhorizontal="true" android:layout_width="fill_parent" android:layout_height="wrap_content"/> 在 Activity 中获得 ad_container, 然后添加 MobiSageAdBanner 到 ad_container 中, 示例代码 : // 获取广告容器 LinearLayout ad_container = (LinearLayout) findviewbyid(r.id.ad_container) ; // 实例化广告 ( 广告尺寸自适应不同分辨率设备 ), 传入相应类型 slottoken MobiSageAdBanner adv = new MobiSageAdBanner(this, "Y2JjsAz07nlTdkU55PC4Xu9F"); // 将广告加入容器 ad_container.addview(adv.getadview()); 销毁广告广告不再使用时, 通过下面的方法将其销毁 : if(adv!= null){ // 销毁广告 adv.destroyadview (); adv = null; 广告通知 横幅广告提供了五个广告相关的通知, 如下所示 : private MobiSageAdBannerListener mlistener = new MobiSageAdBannerListener() { // 横幅广告请求成功时, 此接口被回调, 横幅广告可以展示 public void onmobisagebannersuccess(mobisageadbanner adview) { // 横幅广告展示或轮播成功时, 此接口被回调, 多用于聚合中统计广告展示数 public void onmobisagebannershow (MobiSageAdBanner adview) { 6

7 // 横幅广告被点击时, 此接口被回调, 多用于聚合中统计广告点击数 public void onmobisagebannerclick (MobiSageAdBanner adview) { // 横幅广告展示或轮播失败时, 此接口被回调, 多用于聚合中切换广告平台,msg 为错误信息 public void onmobisagebannererror (MobiSageAdBanner adview, String msg) { // 打开 Landing Site 之后, 此接口被回调 public void onmobisagebannerpopupwindow (MobiSageAdBanner adview) { // 关闭 Landing Site 之后, 此接口被回调 public void onmobisagebannerhidewindow (MobiSageAdBanner adview) { ; 7

8 1.6 信息流广告 信息流广告特点是可以跟应用进行紧密结合, 自定义广告 UI 展现和广告元素组合, 适用于信息流 图片流等等更广泛应用进行集成 创建广告 通过调用下面的方法来实例化信息流广告 : // 实例化广告, 传入上下文, 广告位 slottoken, 期望宽和期望高,hashmap 为高级选项, 后面会讲用法 HashMap<String, Object> hashmap = new HashMap<String, Object>(); MobiSageAdNative adnative = new MobiSageAdNative(this,"bWxtvgL64HddeEs36v62UOFD", 300, 170, hashmap); 构造方法中的宽和高必须都传入 注意 : 根据宽高请求广告 ( 宽高比在 之间为有效 size), 我们会根据有效 size 自适应填充广告内容 创建信息流广告传入的宽高与系统原生控件一样, 即实际像素 如果创建一个宽为 400 的广告视图, 那么在任何机型上都是 400 像素宽, 所以开发者创建广告的时候为了适配不同尺寸, 需将传入尺寸乘以机器分辨率以适应不同机型 通过调用下面的方法来实例化多个信息流广告 : // 实例化广告, 传入上下文, 广告位 slottoken, 请求广告个数, 期望宽和期望高,hashmap 为高级选项, 后面会讲 用法 HashMap<String, Object> hashmap = new HashMap<String, Object>(); MobiSageAdNativeFactory adnative = new MobiSageAdNativeFactory(this,"bWxtvgL64HddeEs36v62UOFD",5, 300, 170, hashmap); 按组请求的信息流广告一次最多请求 10 个. MobiSageAdNativeFactory.getAdNatives() 为返回的广告对象数组. 广告分类 8

9 在广告请求前输入期望请求的广告分类, 地理位置, 及 app 信息 可在构造方法中最后加入三个参数, 来精确投放广告. 第一个参数类型为数组, 里面放请求广告类型的标签. String[] tag = {"ts", "ss", "aa"; 第二个参数类型为 int, 标志着是正选还是反选,0 是正选,1 是反选. int minver = 0; 第三个参数类型为 HashMap, 里面放入应用和用户的信息,HashMap 里面结构如下 : "customtag":{ "appinfo":{ "content": ["aa","bb"], "channel": [ {"s":" 手机 ", "f":" 新闻 ", "t":"android", {"s":" 平板 ", "f":" 科技 ", "t":"apad"], "usertag":{ "lon":100, "bcircle": "["abc","efg"]", "address":"xx 路 xx 号 ", "province":" 北京 ", "addtag": "[" 大学 ", " 教育 "]", "addname":" 北京大学 ", "lat":100, "country":" 中国 ", "city":" 北京 " 代码如下 : 9

10 HashMap<String, Object> customtag = new HashMap<String, Object>(); HashMap<String, Object> usertag = new HashMap<String, Object>(); HashMap<String, Object> appinfo = new HashMap<String, Object>(); usertag.put("country", " 中国 "); usertag.put("province", " 北京 "); usertag.put("city", " 北京 "); usertag.put("address", "xx 路 xx 号 "); usertag.put("addname", " 北京大学 "); usertag.put("addtag", "[\" 大学 \",\" 教育 \"]"); usertag.put("bcircle", "[\"abc\",\"efg\"]"); usertag.put("lon", 100); usertag.put("lat", 100); JSONArray channel = new JSONArray(); JSONObject cone = new JSONObject(); JSONObject ctwo = new JSONObject(); try { cone.put("f", " 新闻 "); cone.put("s", " 手机 "); cone.put("t", "android"); ctwo.put("f", " 科技 "); ctwo.put("s", " 平板 "); ctwo.put("t", "apad"); catch (JSONException e) { e.printstacktrace(); channel.put(cone); channel.put(ctwo); appinfo.put("channel", channel); JSONArray content = new JSONArray(); content.put("aa"); content.put("bb"); appinfo.put("content", content); customtag.put("usertag", usertag); customtag.put("appinfo", appinfo); 详情见 sample 信息流经典类型. 获取广告信息 信息流广告与普通横幅广告的差别除了可自定义尺寸外, 主要的差别在于信息流广告会返回广告本身的一些信息 目前包含的信息有 : 广告宽度, 广告高度 ( 注 : 不是请求的宽高而是返回广告的宽高, 服务器会根据开发者请求的宽高返回接近的尺寸, 此处获得的即为实际尺寸 ), 广告标题, 广告 logo 网址 ( 为一张图片 ),image, 广告描述信息, 广告星级, 广告包大小, 有多少人在玩 ( 使用 ) 人数, 评论数 10

11 广告信息返回时候会有通知 ( 请看下面广告通知 ), 开发者可在接到相应通知后获得这些信息 然后开发者可以将广告 view 与广告信息拼装成自己喜欢的形式展示出来 : int width = adnative.getadwidth(); // 获取广告实际宽度 int height = adnative. getadheight(); // 获取广告实际高度 HashMap<String, Object> hashmap = adnative. getcontent(); // 获取广告信息, 返回一个 hashmap, 通过获得到的 hashmap 获取广告的各种信息, 对应的 key 如下, 获得的 value 都为 object 类型, 需转型 hashmap.get("width"); // 广告实际宽度 ( 同上面 getadwidth() 一样 ),int 类型 hashmap.get("height"); // 广告实际高度 ( 同上面 getadheight() 一样 ),int 类型 hashmap.get("title"); // 广告标题,String 类型 hashmap.get("image"); // 广告展示图片链接地址,String 类型 hashmap.get("logo"); // 广告对应应用 logo 图片链接地址,String 类型 hashmap.get("desc"); // 广告描述,String 类型 hashmap.get("star"); // 广告星级,double 类型 hashmap.get("person"); // 在线人数 int 类型 hashmap.get("adstatus"); // 广告状态,int 类型 hashmap.get("ratingnum"); // 广告评论数,int 类型 hashmap.get("id");// 广告唯一标识,int 类型 广告状态指当前广告下载状态, 开发者在自定义 UI 时, 可进行广告状态引导, 状态信息请参考以下 表格 : 状态码 含义 建议开发者按钮显示文案 0 下载失败 点击重试 1 未下载 下载 2 下载中 下载中 3 下载完成 点击安装 4 安装完成 点击启动 11

12 广告通知 单个信息流广告提供了以下广告相关的通知, 如下所示 : private MobiSageAdNativeListenermListener = new MobiSageAdNativeListener () { // 信息流广告视图内容加载成功时, 此接口被回调, 可在接到此通知后展示广告 public void onmobisagenativesuccess (MobiSageAdNative adview) { // 信息流广告展示时, 此接口被回调, 多用于聚合中统计广告展示数 public void onmobisagenativeshow (MobiSageAdNative adview) { // 打开 Landing Site 之后, 此接口被回调, 一般情况下不用处理 public void onmobisagenativepopupwindow (MobiSageAdNative adview) { // 关闭 Landing Site 之后, 此接口被回调, 一般情况下不用处理 public void onmobisagenativehidewindow (MobiSageAdNative adview) { // 信息流广告视图内容加载失败时, 此接口被回调, 多用于聚合中切换广告平台,msg 为错误信息 public void onmobisagenativeerror (MobiSageAdNative adview, String msg) { // 信息流广告被点击时, 此接口被回调, 多用于聚合中统计广告点击数 public void onmobisagenativeclick (MobiSageAdNative adview) { // 信息流广告信息加载成功时, 此接口被回调, 可在此接口中获取信息流广告信息 public void onmobisagecontentsuccess (MobiSageAdNative adview) { 12

13 // 信息流广告信息加载失败时, 此接口被回调,message 参数为失败原因, 多用于聚合中切换广告平台,msg 为错误信息 public void onmobisagecontentfailed (MobiSageAdNative adview, String message) { ; 信息流单个提供了下载状态监听 MobiSageAdStatusListener mobisageadstatuslistener new MobiSageAdStatusListener() { ; public void updateadstatus(int id, int status) { // id 为下载状态发生变化的广告 id,status 为改变后的状态码, 可按照上边提供的表对照 注意 : 信息流广告会先回调广告信息加载成功接口, 然后加载广告内容, 这样在广告加载成功接口 被回调时, 广告信息已经加载成功 所以可以在广告加载成功后来展示广告, 这时广告的信息肯定也能 获得到 成组的信息流广告提供了以下广告相关的通知, 如下所示 : MobiSageAdNativeFactoryListener mobisageadnativefactorylistener = new MobiSageAdNativeFactoryListener() { message) { public void onmobisagenativegroupsuccess(mobisageadnativefactory adgroup) { // 成组广告成功返回时通知 public void onmobisagenativegrouperror(mobisageadnativefactory adgroup, String // 成组广告请求失败时通知,message 为失败信息 ; 展示广告 13

14 展现形式分为两种 : 广告模板和广告元素 广告模板 : 直接将广告视图放入父 view 中即可 FrameLayout framelayout = new FrameLayout(); framelayout.addview(adnative.getadview()); 广告元素 : 在构造方法的 hashmap 中, 添加一个布尔值,key 和 value 如下 hashmap.put("disabletoload", true);// 不去加载广告资源, 需开发者自己根据返回的元素绘制界面. 界面绘制好后, 需要调用 attachtoview 方法, 否则广告不会展示, 也不可点击 nativead.attachtoview(view);//view 为开发者绘制好的 view 注意 : 如果是开发者自己根据元素绘制的界面一定记得调用 attachtoview 方法, 否则不展示也不可 点击. 广告点击 信息流广告单独提供了一个点击接口, 调用此方法就相当于点击了一次广告 因为信息流广告提 供了一些广告信息供开发者自行拼装展现形式, 开发者可添加一个下载按钮, 点击此按钮调用点击方 法即可 : adnative.handleclick(); 销毁广告 广告不再使用时, 通过下面的方法将其销毁 (): // 广告模板 if(adnative!= null){ 14

15 // 销毁广告 adnative.destroyadview(); adnative = null; // 广告元素 if(adnative!= null){ // 销毁广告 adnative. detachfromview(); 15

16 1.7 插屏广告 创建广告 // 实例化广告, 传入相应类型 slottoken, 广告尺寸自适应不同分辨率设备 MobiSageAdPoster adv = new MobiSageAdPoster(this, "l5axrpgago2ngrhnearmqhuw", MobiSageAdPoster.SIZE_300X250); 插屏广告支持的尺寸及枚举值见下表 : 广告尺寸 枚举值 300X250( 推荐 ) MobiSageAdPoster.SIZE_300X X480 MobiSageAdPoster.SIZE_FULL_SCREEN 插屏的尺寸还可以在官网上动态设置, 如果官网设置了, 则以官网的设置为准. 展示广告 // 建议在预加载成功时调用 adv.show(); 广告通知插屏广告提供了四个广告相关的通知, 如下所示 : private MobiSageAdPosterListener mlistener = new MobiSageAdPosterListener() { 16

17 // 插屏广告预加载成功时, 此接口被回调, 建议在收到此通知后, 展示广告, 否则影响广告展示的成功率 public void onmobisageposterpreshow () { adv.show(); // 插屏广告被点击时, 此接口被回调, 多用于聚合中统计广告点击数 public void onmobisageposterclick () { // 插屏广告请求失败时, 此接口被回调, 多用于聚合中切换广告平台,msg 为错误信息 public void onmobisagepostererror (String msg) { // 插屏广告被关闭或被销毁时, 此接口被回调, 一般情况下不用处理 ; public void onmobisageposterclose (){ 17

18 1.8 开屏广告 创建广告在应用要显示开屏广告 Activity 的 layout 文件里, 添加 android:id, 如下所示 : <?xml version="1.0" encoding="utf-8"?> <FrameLayout xmlns:android=" android:id="@+id/layout_splash" android:layout_width="match_parent" android:layout_height="match_parent">... </FrameLayout> 实例化广告, 需要传入 ViewGroup 和广告展示时预期的方向 ; // 实例化广告, 传入相应类型 slottoken, 广告尺寸自适应不同分辨率设备 MobiSageAdSplash splash = new MobiSageAdSplash(this, "hysfvuoscj+1kkpfahzeuamh", findviewbyid(r.id.layout_splash), MobiSageAdSplash.ORIENTATION_PORTRAIT); 广告方向 竖屏 ( 推荐 ) 横屏 枚举值 MobiSageAdSplash.ORIENTATION_PORTRAIT MobiSageAdSplash.ORIENTATION_LANDSCAPE 广告通知 开屏广告提供了三个广告相关的通知, 如下所示 : // 缓存开屏监听 private MobiSageAdSplashListener mlistener= new MobiSageAdSplashListener () { // 开屏广告展示成功时, 触发此通知, 一般用于统计广告展示次数 public void onmobisagesplashshow() { // 开屏广告展示失败时, 触发此通知 ; 在接收到此通知后, 建议跳转至应用的主界面,msg 为错误信息 18

19 public void onmobisagesplasherror(string msg) { // 开屏广告关闭时, 触发此通知 ; 在接收到此通知后, 建议跳转至应用的主界面 public void onmobisagesplashclose() { ; // 实时开屏监听 //private MobiSageAdRTSplashListener mrtlistener= new MobiSageAdRTSplashListener () { // 开屏广告展示成功时, 触发此通知, 一般用于统计广告展示次数 // //public void onmobisagertsplashshow() { // // 开屏广告展示失败时, 触发此通知 ; 在接收到此通知后, 建议跳转至应用的主界面,msg 为错误信息 // //public void onmobisagertsplasherror(string msg) { // // 开屏广告关闭时, 触发此通知 ; 在接收到此通知后, 建议跳转至应用的主界面 // //public void onmobisagertsplashclose() { // //; 使用注意事项 : 1) 使用开屏广告前要确保您的应用 2 秒以上的启动画面 2) 在开屏广告展现失败或关闭时, 会回调 onmobisagesplasherror/onmobisagesplashclose 方法, 在这两个方法中, 建议开发者进行开屏页面到主页面的跳转 ( 即 Activity 跳转 ) 3) 建议开发者在开屏界面的 Activity 中, 通过 onkeydown 方法, 屏蔽开屏界面的返回键行为 (KeyEvent.KEYCODE_BACK), 以此来保证您的广告展示有效性及收益 19

20 开屏属于弹出式显示广告的形式 SDK 包中的 Sample 提供了完整的开屏使用流程, 建议开发者查 看并在自己的应用 / 游戏中实现该使用方法 20

21 1.9 用户统计 功能简介 : 系统日志可以帮助您统计应用程序的用户数量 平均使用时长 实现方式 : 在产品中加入以下代码, 您将可以从开发者平台, 查看此应用的用户统计报表 : // 启动时调用 MobiSageManager.getInstance().trackSystemEvent(TrackActivity.this, MobiSage_publishID,Mob isageenviroment.app_launching_event); // 退出时调用 MobiSageManager.getInstance().trackSystemEvent(TrackActivity.this, MobiSage_publishID,Mo bisageenviroment.app_terminating_event); 21

22 2. 使用建议 运行及开发环境 : 最低环境为 Android Api Level 8 编译环境为 Android Api Level 19 关于代码混淆 : 由于 mobisage SDK 已经过混淆, 不需再次混淆 在对应用进行混淆时, 请参照以下混淆代码 : -optimizations!code/simplification/arithmetic,!field/*,!class/merging/*,!code/allocation/ variable -dontoptimize -dontwarn -dontwarn com.a.a.a.** -libraryjars libs/mobisagesdk.jar -keep class com.mobisage.android.** {*; -keep interface com.mobisage.android.** {*; -keep class com.msagecore.** {*; -keep interface com.msagecore.** {*; 关于横幅广告的使用 : 横幅广告所在的 activity 当被遮挡或隐藏时, 需将横幅广告释放掉, 以防过多的无效广告请求和展示, 影响广告点击率和收益 关于插屏广告的使用 : 插屏广告支持广告的预加载, 在广告被实例化时, 会启动广告请求缓存线程, 因此建议将插屏广告的实例化前置, 这样在预加载成功的方法被回调时, 调用广告的展示方法, 可以提高广告的填充率 插屏广告在被用户关闭后, 插屏广告会自动释放, 无需在应用中对其再次进行释放 关于开屏广告的使用 : 使用开屏广告前要确保您的应用有自己的 2 秒以上的启动画面, 否则有可能开屏广告在展现前出现黑屏的现像 22

23 关于联系方式 :( 参见 邮箱 电话 : 客服 :QQ: