MW Logo

Android魔窗位SDK集成文档

Google Play专属版SDK


一、集成准备

1.1 获取魔窗Appkey(移动端AndroidManifest.xml内的MW_APPID)

登录魔窗后台管理(http://mgnt.magicwindow.cn),按照步骤提示注册应用。

点击右上角“账户(xxx@xxx.com)”->“App 管理” ,填写相应内容,创建应用。并获取魔窗App Key。

1.2 添加SDK资源文件

jar文件对应列表

平台 Jar 相应版本
魔窗 MagicWindowSDK.jar 最新版
微信 libammsdk.jar(如果项目已经有微信分享功能,则不需要此jar包) 修改日期:2015/7/19 大小:47KB

解压SDK压缩包,将文件夹中的libs内的libammsdk.jar和MagicWindowSDK.jar引入即可。

注意:
① 如果编译时提示微信分享等jar包重复,说明您的代码内已经有libammsdk.jar(微信分享)等jar包。请删除其中一个。
② MagicWindowSDK.jar可以通过gradle的dependeies引入:

1.3 添加权限

1.4 添加activity信息


二、基本功能集成(必加项)

2.1 初始化SDK

在应用程序启动activity中调用。

2.2 session功能

注:Session为基础功能,必须集成,否则无法获取到活动。

方法1:(Android-14之后才起作用。)

在自定义 application 的 onCreate()方法内调用 Session.setAutoSession(this);

如果需要兼容 Android-14 (4.0)之前的版本,请用以方法:

方法2:

在BaseActivity(父类activity)或者每个activity的相应函数里加入以下代码:

注意:
① 如果调用Process.kill或者System.exit之类的方法杀死进程,请务必在此之前调用Session.onKillProcess()方法,用来保证Session正确。
② 如果写了BaseActivity(父类activity),则只在相应的BaseActivity内添加上面的代码即可,不要重复添加。
③ 如果需要混淆代码,为了保证sdk的正常使用,需要在proguard.cfg加上下面两行配置:
-keep class com.tencent.mm.sdk.** {*;}
-keep class cn.magicwindow.** {*;}
-dontwarn cn.magicwindow.**

三、创建广告

3.1 WEB端

登录魔窗后台管理(http://mgnt.magicwindow.cn/),按照步骤获取相应的魔窗位key.

3.2 普通广告

3.2.1 广告展示接口

3.2.2 RenderAd说明

3.2.3 广告点击接口

3.2.4 广告曝光统计接口

3.2.5 示例代码

3.3 信息流广告

3.3.1 信息流数据请求接口

3.3.2 获取信息流展示View

3.3.3 广告曝光统计接口

3.3.4 示例代码

3.4 其他

如果广告只展示一张图片,如同第三部分的魔窗位展示,可以用MWImageView内的bindEventWithAd(Activity act,String windowKey)直接展示。


四、创建魔窗位

4.1 WEB端

登录魔窗后台管理(http://mgnt.magicwindow.cn/),按照步骤获取相应的魔窗位key。

4.2 魔窗位集成

移动端最简单的ImageView显示。除了这个方法,我们还提供了具体的后台API数据接口。各开发者如果想自定义布局,可以通过这些接口获取相应数据。下面首先介绍ImageView布局。

4.2.1 布局layout

在需要展示入口的xml文件,把ImageView替换为cn.magicwindow.MWImageView即可。

代码示例:

4.2.2 绑定魔窗位置ID

绑定魔窗位:

判断活动是否开启:

如果想判断此活动是否开启,请用此API。以此为依据,可以在没活动的时候隐藏窗体

推荐用法:

4.2.3 魔窗位曝光统计

此在需要的地方调用

4.3 其他

4.3.1 自定义魔窗窗体

如果你想自定义魔窗的展示布局,可以根据4.2.3或者4.2.4的API获取相应的活动内容,从而自定义布局,以及添加点击事件跳转到相应的webview。

首先明确一个概念,魔窗在后台可配置如下三项内容:①活动展示图片。②活动标题。③活动内容。

我们可以根据这三个要素自定义魔窗的展示窗体。

4.3.2 其他API

1)、手动更新活动

前提:准确集成2.2 session统计

活动默认更新策略是“随着session程序自动刷新活动”。但是我们依旧提供update()接口,通过此接口来实现单个活动或者全部活动(windowKey传值为null时更新全部活动)

示例:

然后监听我们提供的broadcast,从而实时刷新活动。

cn.magicwindow.marketing.update.MW_MESSAGE

示例:

例子在相应的Activity或者Fragment内:

2)、活动图片URL(参见4.3.1自定义魔窗位)

3)、活动名称(参见4.3.1自定义魔窗位)

4)、活动描述(参见4.3.1自定义魔窗位)

5)、点击响应(参见4.3.1自定义魔窗位)

魔窗在APP中自定义展示,需要添加点击事件,点击响应事件

6)、活动的URL

7)、检测所有活动状态

如果你想一下子检测所有开启的活动,那么下面这个接口可以满足你的需求。

并且它会把所有开启的活动的windowKey(魔窗位Key)以ArrayList的形式返回给你

8)、检测活动webview生命周期

如果你想要在活动的webview打开或者关闭的时候做一些特殊处理(比如说在webview关闭的时候顺便进入或者关闭某个页面),可用下面的方式

①首先在MWConfiguration打开setWebViewBroadcastOpen(true)
②在AndroidManifest.xml内注册receiver,或者在代码内动态注册(相关代码不再描述)

③自定义的MWBroadCastReceiver类似如下


五、事件统计

5.1 地理位置经纬度传递

如果需要,可通过下面这个API将经纬度传递过来。

5.2 页面统计

5.2.1 只由activity构成的页面

如果您已经完成2.3步骤的代码添加,那么SDK已默认统计了每个Activity的跳转路径。页面统计不需要再添加其他代码。

5.2.2 包含activity、Fragment或者View作为页面的应用

统计程序中包含Fragment的情况比较复杂,首先要明确一些概念。

① TrackAgent.currentEvent().onResume()和TrackAgent.currentEvent().onPause()方法是用来统计应用时长的(也就是Session时长,当然还包括一些其他功能);

② TrackAgent.currentEvent().onPageStart() 和 TrackAgent.currentEvent().onPageEnd() 方法是用来统计页面跳转的。

在仅有Activity的程序中,SDK 自动帮助开发者调用了②中的方法,并把Activity 类名作为页面名称统计。 但是在包含fragment的程序中我们希望统计更详细的页面,所以需要自己调用方法做更详细的统计。 首先,需要在程序入口处MWConfiguration,打开setPageTrackWithFragment(true) 页面统计方式,这样将不会再自动统计Activity。

然后需要做两步集成:

1、使用 onResume 和 onPause 方法统计时长, 这和基本统计中的情况一样(针对Activity);

2、使用 onPageStart 和 onPageEnd 方法统计页面(针对页面,页面可能是Activity也可能是Fragment或View)。

对于一些典型应用,比如页面是直接放在Activity里面的,统计代码大约是这样:

如果页面是使用FragmentActivity+Fragment实现的,需要在FragmentActivity中统计时长:

并在其包含的Fragment中统计页面:

需要注意的是这些方法的调用,需要保证线性不交叉,每个start都有一个end配对,如下:

onPageStart -> onPageEnd -> onPageStart -> onPageEnd -> onPageStart -> onPageEnd

这样才能保证每个页面统计的正确。

注意:如果开发者调用Process.kill或者System.exit之类的方法杀死进程,请务必在此之前调用TrackAgent.currentEvent().onKillProcess()方法,用来保存统计数据。

5.3 自定义事件类型

自定义事件分为2大类:

(1) 统计次数(时间点事件):统计指定行为被触发的次数。

(2) 统计时长(时间段事件):统计指定行为消耗的时间,单位为秒。需要begin接口与end接口成对使用才生效。

其中每类事件都有Key-Value参数类型和不定长字符串参数类型。

注意:
① 如果代码同时使用了这2种参数类型,event_id最好不一样。
② event_id需要先在魔窗网站上面注册,才能参与正常的数据统计。event_id不能包含空格或转义字符。

5.3.1 注册自定义事件

自定义事件的注册(配置)包括事件id的注册和事件,id下参数信息的注册。

step1:登陆魔窗前台,选择左边选择“自定义事件”。

step2:选择“新增事件”,按照需求填写事件id、key、value等信息。

step3:可以在查看详情下的“参数”查看事件id下所有参数上报的明细。

5.3.2 统计场景举例

(1) 时间点事件

统计发生次数

统计带属性的行为触发次数

统计电商应用中“购买”事件发生的次数,以及购买的商品类型及数量,那么在购买的函数里调用。

代码示例:

(2) 时间段事件

代码示例:

5.4 错误统计

SDK从内建错误统计,不需要开发者再手动集成。SDK自动捕获程序崩溃日志,并在程序下次启动时发送到服务器。

如不需要错误统计功能,在初始化MWConfiguration时调用setCrashTrackOff关闭。

如果开发者自己捕获了错误,需要上传到友盟服务器可以调用下面方法:

5.5 渠道(channel)填写

<meta-data android:name="MW_CHANNEL" android:value="Channel ID"/>中的Channel ID替换为您应用的推广渠道名称。

例如在豌豆荚渠道推广此包,代码示例:

如不想在manifest里配置渠道(channel),可在Activity中配置,只需在MWConfiguratio初始化的时候指定即可。

注意:AndroidManife.xml里的优先级最高。如果此处定义了channel,则优先使用此定义。

命名规范例:

① 可以由英文字母、阿拉伯数字、下划线、中划线、空格、括号组成,可以含汉字以及其他明文字符,但是不推荐使用;

② 首尾字符不可以为空格;

③ 最多256个字符;

5.6 用户信息统计

如果需要将用户的一些信息,比如用户名或者手机号(注意隐私)储存到魔窗服务器,以便节省某些活动的再次输入。可利用以下接口传递。

在用户登录时,调用:

在用户注销登录时,调用:

其中UserProfile各接口如下:

5.7 区域定向

魔窗的区域定向,默认使用ip定位。调用以下API通过行政区划代码可手动定位。定位后会自动刷新活动

初始化时,可调用MWConfigration内的setCityCode()定位。或者在其他时候调用TrackAgent.currentEvent().TracksetCityCode(String cityCode);

或者

TrackAgent.currentEvent().setCityCode(String cityCode, UpdateMarketingListener listener)

注意:
活动区域仅支持到地级市。(比如只能定位到北京,北京下面的城区不能定位)。
中华人民共和国县以上行政区划代码参考链接:http://files2.mca.gov.cn/www/201510/20151027164514222.htm


6.1 魔窗位支持额外参数

6.1.1 bindEventWithParams说明

例如mLink跳转或 Aba带返回(callback)

ABA跳转解释:例如,通过“美人相机”的mLink跳转到“美人相机”的拍照页面。拍完后,“美人相机”可以根据callback scheme,携带相关信息返回本应用。

如果想让你的魔窗位支持mLink等功能。请调用带有WithParams字样的API。比如:

MWImageView内的bindEventWithParams(),他们与普通的魔窗API是一一对应

列表:

API 参数说明
MWImageView bindEventWithParams(clickParamsBuilder) 见3.2.5
MarketingHelper clickWithParams(clickParamsBuilder) 见3.2.5

6.1.2 ClickParamsBuilder说明

列表:

API 参数说明
ClickParamsBuilder mLinkParam() 魔窗位需要传递的mLink值:
支持JsonObject和Map格式
ClickParamsBuilder landingPageParam() App未安装,跳转到的HTML页面的Url值:
支持JsonObject和Map格式
ClickParamsBuilder AbaCallbackMLinkKey() ABA跳转时回跳的uri:
支持uri或者mLink的服务Key
ClickParamsBuilder AbaCallbackParam() ABA跳转,回跳时的动态参数值:
支持JsonObject格式
ClickParamsBuilder listener() 魔窗位更改点击事件时调用:
ClickParamsBuilder build() Builder模式的最后调用。

6.2 使用自定义Webview展示魔窗内容

此功能为客户提供如下功能:用户用自己的webview来展示魔窗后台的“外部链接”活动的H5页面。

我们可以利用getWebviewURL来获取H5的URL。然后在bindEvent内的点击listener内处理跳转到客户自己的webview。

6.3 自定义webview上部title bar(可选)

如果想自定义webview内的标题栏。可按照如下步骤(如果只修改配色,可直接在魔窗后台修改。如果要更换成图片等样式,必须按照如下配置。)

① 可以为每个魔窗位自定义标题栏

② 可以添加左侧按钮,右侧按钮,也可以显示title,甚至可以用后台自定义的活动名称作为title

如上图所示,整个title bar都可以自定义。红框内的三个内容需要特别注意。

① MWConfiguratio初始化时,调用setCustomWebViewTitleBarOn()。打开自定义开关(此开关打开后,后台魔窗标题配置颜色功能自动失效)

② 在res/layout内新建mw_title_layout.xml,如果为每个魔窗自定义窗体,则新建mw_title_layout_魔窗位Id.xml,如下图(ID内字母转为小写)

xml内具体内容参考:


七、测试与调试

7.1 测试前的准备

确认所需的权限都已经添加:INTERNET, READPHONESTATE等;

确认MW_APPID与WECHAT_APPID已经正确的写入Androidmanifest.xml;

确认MWActivity在Androidmanifest.xml里正确声明;

确认所有的Activity中都调用了onResume和onPause方法;

确认测试手机(或者模拟器)已成功连入网络。

7.2 普通测试流程

使用普通测试流程,请先在程序入口初始化MWConfiguration添加以下代码打开调试模式:

打开调试模式后,您可以在logcat中查看您的数据是否成功发送到魔窗服务器,以及集成过程中的出错原因等。

Log的tag 用途 结果
SDKIntegrationTest 查看集成是否成功 数据是否成功发送到魔窗服务器(the data has sent successfully)
SDKIntegrationDebug SDKIntegrationDebug 查看集成遇到的问题
SDKDebug 其他log 系统调试的一些其他log
注意:请使用普通测试流程,您的测试数据会与用户的真实使用数据同时处理,从而导致一定的数据污染。

八、FAQ

如果对接遇到问题,请参考以下地址:

https://github.com/magicwindow/mw-sdk-faq/blob/master/android-sdk-faq.md