MagicWindowSDK 使用文档（Android）
一 快速集成
1.1 获取魔窗Appkey（移动端AndroidManifest.xml内的MW_APPID）
登录魔窗后台管理（http://mgnt.magicwindow.cn），按照步骤提示注册应用。
进入“应用设置”->”应用管理”->“关联应用” ,如下图所示填写相应内容，创建应用。并获取魔窗AppKey
1.2 安装SDK
jar文件对应列表：
| 平台 |
Jar |
相应版本 |
| 魔窗 |
MagicWindowSDK.jar |
最新版 |
| 微信 |
libammsdk.jar |
修改日期：2015/2/5 大小：149KB |
1.3 添加资源文件和jar文件
方法①：添加工程引用（升级方便，推荐）
解压SDK压缩包，将文件夹中的mw_sdk_library文件夹导入Eclipse（或者Android Studio），并在您的工程中添加对此项目的引用即可。
方法②：添加资源到现有项目中
解压SDK压缩包，将文件夹中的'main/libs'、' main/res'和' main/asserts'文件夹复制到您的项目工程根目录下（如使用'ADT 17'以下用户需要手动添加'libs'下的jar文件到工程Path中）
注意：
①Android studio跟eclipse等IDE的目录结构可能不同，一定要放置正确的目录下！
②如果编译时提示微信分享等jar包重复，说明您的代码内已经有libammsdk.jar(微信分享)等jar包。请删除其中一个。
1.4 添加权限
注意：GPS定位权限可关闭，如果关闭则不会定位用户当前位置。（对策略的精准投放有影响。）
1.5 添加activity以及Service信息
1.6 微信分享，回调activity
a. 在你的包名相应目录下新建一个wxapi目录，并在该wxapi目录下新增一个WXEntryActivity类，该类继承自MWWXHandlerActivity（例如应用程序的包名为net.sourceforge.simcpux，则新添加的类如下图所示）
示例代码如下：
public class WXEntryActivity extends MWWXHandlerActivity{
// 微信发送请求到第三方应用时，会回调到该方法
@Override
public void onReq(BaseReq req) {
//super.onReq(req);必须加
super.onReq(req);
//todo: 在下面添加你可能需要实现的代码
}
// 第三方应用发送到微信的请求处理后的响应结果，会回调到该方法
@Override
public void onResp(BaseResp response){
//super.onResp(response);必须加
super.onResp(response);
//todo: 在下面添加你可能需要实现的代码
}
}1.7 渠道（channel）填写
将
例如在豌豆荚渠道推广此包，代码示例：
如不想在manifest里配置渠道（channel），可在Activity中配置：只需在程序启动时的Activity中调用此接口：
MagicWindowSDK.setChannel(Stringchannel)注意：AndroidManife.xml里的优先级最高。如果此处定义了channel，则优先使用此定义。
命名规范：
可以由英文字母、阿拉伯数字、下划线、中划线、空格、括号组成，可以含汉字以及其他明文字符，但是不推荐使用。
首尾字符不可以为空格
最多256个字符
"unknown" 及其各种大小写形式，作为魔窗保留的字段，不可以作为渠道名
二 初始化SDK（必加项）
请在应用程序的入口Activity的OnCreate()方法中下添加以下代码：
MagicWindowSDK.initSDK(this);如果希望获取SDK的版本，可以调用
MagicWindowSDK.getMagicWindowSDKVersion(); 三 创建活动
3.1 WEB端
登录魔窗后台管理（http://mgnt.magicwindow.cn/），按照步骤获取相应的魔窗位key
3.2 移动端
移动端最简单的ImageView显示。除了这个方法，我们还提供了具体的后台API数据接口。各开发者如果想自定义布局，可以通过这些接口获取相应数据。下面首先介绍ImageView布局。
3.2.1 布局layout
在需要展示入口的xml文件，把ImageView替换为com.zxinsight.MWImageView即可
代码示例：
3.2.2 绑定魔窗位置ID
代码示例：
MWImageView imageView = (MWImageView)findViewById(R.id.mw_banner);
// windowKey魔窗窗体ID
imageView.bindEvent("windowKey ");3.2.3 判断活动是否开启
如果想判断此活动是否开启，请用此API。以此为依据，可以在没活动的时候隐藏窗体
// context页面的设备上下文
// windowKey魔窗窗体ID
MarketingHelper.currentMarketing(context). isActive ("windowKey")3.2.4 自定义魔窗窗体
魔窗在后台可配置如下内容：①活动展示图片。②活动标题。③活动内容。
我们可以根据这三个要素自定义魔窗的展示窗体。
示例：
//todo: 自定义魔窗位方式1
topLayout5 = (RelativeLayout) findViewById(R.id.top_5_layout);
topTitle5 = (TextView) findViewById(R.id.top_5);
topImg5 = (ImageView) findViewById(R.id.ic_top_5);
if (marketingHelper.isActive(Constant.MW_2)) {
//获取标题
topTitle5.setText(marketingHelper.getTitle(Constant.MW_2));
//获取背景图
ImageLoader.getInstance().displayImage(marketingHelper.getImageURL(Constant.MW_2),topImg5);
topLayout5.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
//跳转到相应的webView
marketingHelper.toNativeWebView(Constant.MW_2);
}
});
}
//end
//todo: 自定义魔窗位方式2renderMarketing接口在2.3版本开放
customLayout1 = (RelativeLayout)findViewById(R.id.custom_style_layout_1);
customImg1 = (ImageView) findViewById(R.id.img1);
customTitle1 = (TextView) findViewById(R.id.title1);
customDescription1 = (TextView) findViewById(R.id.description1);
//Constant.MW_3 为魔窗位的key，customLayout1为点击响应的layout，customImg1为背景图，customTitle1标题，customDescription1描述
marketingHelper.renderMarketing(Constant.MW_3, customLayout1,customImg1, customTitle1,customDescription1);
//end
//todo: 自定义魔窗位方式3renderMarketing接口在2.3版本开放
customLayout2 = (RelativeLayout)findViewById(R.id.custom_style_layout_2);
customImg2 = (ImageView) findViewById(R.id.img2);
customTitle2 = (TextView) findViewById(R.id.title2);
customDescription2 = (TextView) findViewById(R.id.description2);
marketingHelper.renderMarketing(Constant.MW_4, customLayout2, new RenderListener() {
@Override
public void setTitle(String s) {
customTitle2.setText(s);
}
@Override
public void setDescription(String s) {
customDescription2.setText(s);
}
@Override
public void setImage(String s) {
ImageLoader.getInstance().displayImage(s,customImg2);
}
});
//end
3.2.5 活动其他API
通过3.2.1和3.2.2已经完成魔窗的完整展示以及跳转等所有功能（但展示的仅仅是一张图片），如果你想自定义魔窗的展示布局，可以根据下面的API获取相应的活动内容，从而自定义布局，以及添加点击事件跳转到相应的webview。
①更新活动
活动默认更新策略是“程序启动时刷新活动”，如果有需要，你可以通过以下接口来实现单个活动或者全部活动（windowKey传值为null时更新全部活动）
// context页面的设备上下文
// windowKey魔窗窗体ID
// listener更新后的回调函数。
MarketingHelper.currentMarketing(context). updateMarketing(String windowKey, UpdateMarketingListener listener)
示例：
MarketingHelper.currentMarketing(mContext).updateMarketing(“windowKey”, new UpdateMarketingListener() {
@Override
public void success() {
Log.e("update maketing",”windowKey = ”+ MarketingHelper.currentMarketing(mContext).getActivityKey(“windowKey”));
}
@Override
public void failed(String error) {
Log.e("update maketing",”error msg = ”+ error);
}
}②活动展示图片URL（参见3.2.4自定义魔窗位方式1）
// context页面的设备上下文
// windowKey魔窗窗体ID
MarketingHelper.currentMarketing(context).getImageURL("windowKey")③活动名称（参见3.2.4自定义魔窗位方式1）
// context页面的设备上下文
// windowKey魔窗窗体ID
MarketingHelper.currentMarketing(context). getTitle("windowKey")④活动的相关描述（参见3.2.4自定义魔窗位方式1）
// context页面的设备上下文
// windowKey魔窗窗体ID
MarketingHelper.currentMarketing(context). getDescription("windowKey")⑤跳转到相应的webView（参见3.2.4自定义魔窗位方式1）
魔窗在APP中自定义展示，需要添加点击事件，点击响应事件
// context页面的设备上下文
// windowKey魔窗窗体ID
MarketingHelper.currentMarketing(context).toNativeWebView ("windowKey")⑤点击直接分享
// Activity调用的activity
// windowKey魔窗窗体ID
//sUrl 分享的连接，如果传null，则根据windowKey自动获取分享连接
ShareHelper.share(Activity,mWindowKey,sUrl);
//或
ShareHelper.share(Activity,mWindowKey);
四 事件统计（必加项）
4.1 页面统计
4.1.1 普通activity页面统计
在需要页面追踪的activity的响应函数里加入以下代码：
@Override
protected void onPause() {
TrackAgent.currentEvent().onPause(this);
super.onPause();
}
@Override
protected void onResume() {
TrackAgent.currentEvent().onResume(this);
super.onResume();
}
注意：如果想给当前页面自定义名字，可以将
TrackAgent.currentEvent().onPause(this);更换为
TrackAgent.currentEvent().onPause(this, “您的页面名字”);4.1.2 带有Fragment的页面统计
Fragment页面必须带有页面名称。
TrackAgent.currentEvent().onPause(getActivity(),“您的页面名字”);这样处理后，系统会自动把包含此Fragment的activity的页面统计忽略掉。（同一个activity之内的Fragment页面切换可以被统计。）
4.1.3地理位置经纬度传递
如果需要，可通过下面这个API将经纬度传递过来。
// context页面的设备上下文
// latitude经度(Double)
// longitude纬度(Double)
TrackAgent.currentEvent().setLocation(context, latitude,longitude);4.1.4 自定义事件类型
自定义事件分为2大类：
(1)统计次数（时间点事件）：统计指定行为被触发的次数。
(2)统计时长（时间段事件）：统计指定行为消耗的时间，单位为秒。需要begin接口与end接口成对使用才生效。
其中每类事件都有Key-Value参数类型和不定长字符串参数类型。
注意：
①如果代码同时使用了这2种参数类型，event_id最好不一样。
②event_id需要先在魔窗网站上面注册，才能参与正常的数据统计。event_id不能包含空格或转义字符。
4.1.5 注册自定义事件
自定义事件的注册（配置）包括事件id的注册和事件，id下参数信息的注册。
step1：登陆魔窗前台，选择左边选择“自定义事件”。
step2：选择“新增事件”，按照需求填写事件id、key、value等信息。
step3：可以在查看详情下的“参数”查看事件id下所有参数上报的明细。
4.1.6 统计场景举例
（1） 时间点事件
统计发生次数
// context页面的设备上下文
// eventId事件标识
TrackAgent.currentEvent().customEvent(Context context,"event id");统计带属性的行为触发次数
// context页面的设备上下文
// eventId事件标识
// properties事件参数的键值对
TrackAgent.currentEvent().customEvent(Context context,"event id", Map);
代码示例：
统计电商应用中“购买”事件发生的次数，以及购买的商品类型及数量，那么在购买的函数里调用：
HashMapmap = new HashMap();
map.put("type","book");
map.put("quantity","3");
MobclickAgent.onEvent(mContext,"purchase", map);
TrackAgent.currentEvent().customEvent(Context context,"event id", map); （2）时间段事件
代码示例：
// context页面的设备上下文
// eventId事件标识
// properties 事件参数的键值对
//调用位置：事件开始时调用
TrackAgent.currentEvent().customEventStart(Contextcontext, String eventId );
//调用位置：事件结束后调用
TrackAgent.currentEvent().customEventEnd(Context context,String eventId, Map properties); 4.1.7 错误统计
Android统计SDK从V4.6版本开始内建错误统计，不需要开发者再手动集成。SDK自动捕获程序崩溃日志，并在程序下次启动时发送到服务器。
如不需要错误统计功能，可通过此方法关闭 TrackAgent.currentEvent().shutDownCrashTrack(Context context);
如果开发者自己捕获了错误，需要上传到友盟服务器可以调用下面方法：
TrackAgent.currentEvent().reportError(Context context,String error)
//或
TrackAgent.currentEvent().reportError(Context context,Throwable e)注意
如果需要混淆代码，为了保证sdk的正常使用，需要在proguard.cfg加上下面两行配置：
-keep class com.tencent.mm.sdk.** {*;}
-keep class com.zxinsight.** {*;}五 测试与调试
5.1 测试前的准备
Ÿ 确认所需的权限都已经添加：INTERNET, READPHONESTATE等
Ÿ 确认MW_APPID与WECHAT_APPID已经正确的写入Androidmanifest.xml
Ÿ 确认MWActivity与SDKService在Androidmanifest.xml里正确声明
Ÿ 确认所有的Activity中都调用了onResume和onPause方法
Ÿ 确认测试手机(或者模拟器)已成功连入网络
注意：如果你的项目之前已经集成了shareSDK的分享功能，请参照:
“SDK文档-Android-with-ShareSDK.pdf”
5.2 普通测试流程
使用普通测试流程，请先在程序入口添加以下代码打开调试模式：
MagicWindowSDK.setDebugMode( true ); 打开调试模式后，您可以在logcat中查看您的数据是否成功发送到魔窗服务器，以及集成过程中的出错原因等。
| Log的tag |
用途 |
结果 |
| SDKIntegrationTest |
查看集成是否成成功 |
数据是否成功发送到魔窗服务器（the data has sent successfully） |
| SDKIntegrationDebug |
集成遇到问题时的log |
查看集成遇到的问题 |
| SDKDebug |
其他log |
系统调试的一些其他log |
注意：请使用普通测试流程，您的测试数据会与用户的真实使用数据同时处理，从而导致一定的数据污染。