MagicWindowSDK 使用文档（Android）

 

 

 

 

MagicWindowSDK

使用文档（Android）

V2.2  

一        快速集成

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    添加权限

<!-- 连接互联网Internet权限，以便向我们的服务器端发送数据。 -->
   <uses-permission android:name="android.permission.INTERNET"/>
    <!-- 检测网络状态 -->
    <uses-permissionandroid:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- 获取用户手机的IMEI，用来唯一的标识用户。 -->
<uses-permissionandroid:name="android.permission.READ_PHONE_STATE" />
<uses-permissionandroid:name="android.permission.MOUNT_UNMOUNT_FILESYSTEMS" />
 
    <!-- 缓存资源优先存入SDcard -->
   <uses-permissionandroid:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <!—wifi状态 -->
   <uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE" />
   <uses-permission android:name="android.permission.GET_ACCOUNTS"/>
   <uses-permissionandroid:name="android.permission.USE_CREDENTIALS" />
   <uses-permissionandroid:name="android.permission.MANAGE_ACCOUNTS" />
  <!-- GPS定位权限 -->
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permissionandroid:name="android.permission.ACCESS_FINE_LOCATION" />
  <!—判断程序是否在前台运行 -->
<uses-permission android:name="android.permission.GET_TASKS" />

注意：GPS定位权限可关闭，如果关闭则不会定位用户当前位置。（对策略的精准投放有影响。）

1.5    添加activity以及Service信息

<!—后台service 必须注册！！！-->
<service android:name="com.zxinsight.analytics.service.SDKService"/>
<!—总的activity，必须注册！！！ -->
<activityandroid:name="com.zxinsight.common.base.MWActivity"
android:exported="true"
android:configChanges="orientation|keyboardHidden|screenSize|navigation"/>
  <!--微信分享回调 -->
       <activity
           android:name=".wxapi.WXEntryActivity"
           android:theme="@android:style/Theme.Translucent.NoTitleBar"
           android:configChanges="keyboardHidden|orientation|screenSize"
           android:exported="true"
           android:launchMode="singleTop" />
 
<!—MW sdk ID 此处跟activity同级，需要放在Application内，MW_APPID（也就是后台的”魔窗AppKey”）不能更改 -->
       <meta-data
           android:name="MW_APPID"
android:value="您的魔窗AppId" />
<!—渠道名称MW_CHANNEL不能更改 -->
       <meta-data
           android:name="MW_CHANNEL"
           android:value="WanDouJia" />

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）填写

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

例如在豌豆荚渠道推广此包，代码示例：

<meta-dataandroid:name="MW_CHANNEL" android:value="Wandoujia"/>

如不想在manifest里配置渠道（channel），可在Activity中配置：只需在程序启动时的Activity中调用此接口：

MagicWindowSDK.setChannel(Stringchannel)

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

命名规范：

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

首尾字符不可以为空格

最多256个字符

"unknown" 及其各种大小写形式，作为魔窗保留的字段，不可以作为渠道名

二         初始化SDK（必加项）

请在应用程序的入口Activity的OnCreate()方法中下添加以下代码：

MagicWindowSDK.initSDK(this);

 

如果希望获取SDK的版本，可以调用

MagicWindowSDK.getMagicWindowSDKVersion();<span style="font-weight: bold; font-family: Arial, Helvetica, sans-serif; background-color: rgb(255, 255, 255);"> </span>

三        创建活动

3.1    WEB端

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

3.2    移动端

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

3.2.1     布局layout

在需要展示入口的xml文件，把ImageView替换为com.zxinsight.MWImageView即可

代码示例：

<com.zxinsight.MWImageView
           android:layout_width="match_parent"
           android:layout_height="130dp"
           android:layout_marginTop="70dp"
           android:scaleType="fitXY"
android:id="@+id/mw_banner"/>

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     自定义魔窗窗体

魔窗在后台可配置如下内容：①活动展示图片。②活动标题。③活动内容。

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

示例：
<span style="color:#3333ff;"><span style="white-space:pre">	</span>//todo: 自定义魔窗位方式1</span>
       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
 
       <span style="color:#3333ff;">//todo: 自定义魔窗位方式2renderMarketing接口在2.3版本开放</span>
       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
 
       <span style="color:#3333ff;">//todo: 自定义魔窗位方式3renderMarketing接口在2.3版本开放</span>
       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)
<span style="color:#3333ff;">示例：</span>
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);

更换为

<span style="color:#ff0000;">TrackAgent.currentEvent().onPause(this, “您的页面名字”);</span>

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<String,String>);
<span style="color:#3333ff;">代码示例：</span>
统计电商应用中“购买”事件发生的次数，以及购买的商品类型及数量，那么在购买的函数里调用：
HashMap<String,String>map = new HashMap<String,String>();
map.put("type","book");
map.put("quantity","3");
MobclickAgent.onEvent(mContext,"purchase", map); 
TrackAgent.currentEvent().customEvent(Context context,"event id", map);

（2）时间段事件

<span style="color:#3333ff;">代码示例：</span>
// context页面的设备上下文
// eventId事件标识
// properties 事件参数的键值对
//调用位置：事件开始时调用
TrackAgent.currentEvent().customEventStart(Contextcontext, String eventId );
//调用位置：事件结束后调用
TrackAgent.currentEvent().customEventEnd(Context context,String eventId, Map<String,String> 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

 

注意：请使用普通测试流程，您的测试数据会与用户的真实使用数据同时处理，从而导致一定的数据污染。