友盟Android SDK使用方法

下载SDK

重要说明:AIRec需要配合友盟基础组件库 umeng-common-9.1.0及以上版本。

1. Android SDK下载

2. 解压下载后的zip文件,将得到common目录下的基础组件库umeng-common-9.1.0.jar拷贝到目标工程libs目录下,并将其加入工程依赖。

3. 将最新版本智能推荐SDK包(AIRec SDK以aar方式提供)拷贝到目标工程libs目录下,并将其加入工程依赖。

34

基础SDK初始化

  1. 在友盟官网注册账号,并申请Appkey。友盟基础组件库的初始化函数需要传入此Appkey。

  2. 在目标工程Application.onCreate函数中执行友盟基础组件库初始化函数,设置统计SDK页面统计模式,如果您的工程没有实现Application.onCreate函数,请自行实现Application类并将其加入AndroidManifest.xml清单文件。下面的示例代码摘自AIRec SDK集成Demo工程。

    package com.umeng.airecdemo;
    import android.app.Application;
    import android.content.Context;
    import android.content.pm.ApplicationInfo;
    import android.content.pm.PackageManager;
    import android.text.TextUtils;
    import android.util.Log;
    import com.umeng.airec.RecAgent;
    import com.umeng.analytics.MobclickAgent;
    import com.umeng.commonsdk.UMConfigure;
    import java.util.HashMap;
    import java.util.Map;
    public class MyApp extends Application {
     private final static String APPKEY = "appkey";
     private final static String CHANNEL = "channel";
     private final static String DEFAULT_APPKEY = "58edcfeb310c93091c000be2";
     private final static String DEFAULT_CHANNEL = "Unknown";
     @Override
     public void onCreate() {
         super.onCreate();
         Context appContext = this;
         String appkey = DEFAULT_APPKEY;
         String channel = DEFAULT_CHANNEL;
         Map config = getAppkeyAndChannel(appContext);
         if (config != null) {
             if (config.containsKey(APPKEY)) {
                 appkey = (String)config.get(APPKEY);
             }
             if (config.containsKey(CHANNEL)) {
                 channel = (String)config.get(CHANNEL);
             }
         }
         // 友盟SDK调试Log开关,App上线前请关闭Log开关
         UMConfigure.setLogEnabled(true);
         // 友盟SDK初始化,需要设置友盟Appkey(需从友盟官网注册申请),及应用发布渠道
         // 友盟SDK初始化说明文档: https://developer.umeng.com/docs/66632/detail/101814
         UMConfigure.init(this, appkey, channel, UMConfigure.DEVICE_TYPE_PHONE, null);
         // 友盟统计SDK页面采集模式,建议使用自动页面采集
         // 友盟统计SDK集成说明: https://developer.umeng.com/docs/66632/detail/101848
         MobclickAgent.setPageCollectionMode(MobclickAgent.PageMode.AUTO);
         // AIRec SDK调试Log开关,App上线前请关闭Log开关。
         RecAgent.setDebugMode(true);
         // AIRec SDK初始化
         boolean initStatus = RecAgent.init();
         if (!initStatus) {
             Log.i("RecAgent", "AIRec SDK initialization failed.");
         }
     }
     // 从AndroidManifest.xml中读取预先配置的appkey和channel
     public static Map<String, String> getAppkeyAndChannel(Context ctx) {
         if (ctx == null) {
             return null;
         }
         Map result = new HashMap<String, String>();
         String appkey = null;
         String channelName = null;
         try {
             PackageManager packageManager = ctx.getPackageManager();
             if (packageManager != null) {
                 //注意此处为ApplicationInfo 而不是 ActivityInfo,因为友盟设置的meta-data是在application标签中,而不是某activity标签中,所以用ApplicationInfo
                 ApplicationInfo applicationInfo = packageManager.getApplicationInfo(ctx.getPackageName(), PackageManager.GET_META_DATA);
                 if (applicationInfo != null) {
                     if (applicationInfo.metaData != null) {
                         appkey = applicationInfo.metaData.get("UMENG_APPKEY")+"";
                         channelName = applicationInfo.metaData.get("UMENG_CHANNEL")+"";
                     }
                 }
             }
         } catch (PackageManager.NameNotFoundException e) {
             e.printStackTrace();
         }
         if (!TextUtils.isEmpty(appkey)) {
             result.put(APPKEY, appkey);
         }
         if (!TextUtils.isEmpty(channelName)){
             result.put(CHANNEL, channelName);
         }
         return result;
     }
    }

    如果需要使用友盟统计SDK高级功能,请参考如下链接:友盟统计SDK集成文档

    基础SDK权限授予

    需要在目标工程AndroidManifest.xml清单文件中加入如下权限:

    <!-- 必须的权限 -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />

    基础SDK混淆配置

    如果您的应用使用了代码混淆,请添加如下配置,以避免基础SDK被错误混淆导致SDK不可用。

    -keep class com.umeng.** {*;}
    -keepclassmembers class * {
    public <init> (org.json.JSONObject);
    }
    -keepclassmembers enum * {
     public static **[] values();
     public static ** valueOf(java.lang.String);
    }

    SDK需要引用导入工程的资源文件,通过了反射机制得到资源引用文件R.java,但是在开发者通过proguard等混淆/优化工具处理apk时,proguard可能会将R.java删除,如果遇到这个问题,请添加如下配置:

    -keep public class [您的应用包名].R$*{
    public static final int *;
    }

    智能推荐SDK集成

    SDK API说明

    请在完成友盟基础组件库初始化函数调用之后调用AIRec SDK初始化函数。

    请在调用AIRec SDK初始化函数之后再调用其它功能接口函数。

• 初始化函数 RecAgent.init();

/**
     * 初始化函数
     * @return
     * true:正确初始化,可以正常使用;
     * false: 初始化失败,友盟基础组件库、统计SDK未正确集成及初始化
     */
    public static boolean init();

例子:

 boolean initStatus = RecAgent.init();
   if (!initStatus) {
       Log.i("RecAgent", "AIRec SDK initialization failed.");
   }

实例代码摘自Demo工程如下路径:app/src/main/java/com/umeng/airecdemo/MyApp.java• 调试Log开关函数 RecAgent.setDebugMode(true);

/**
     * 调试Log开关函数,SDK默认情况下调试Log关闭
     * @param debug
     * true: 开启调试Log输出
     * false: 关闭调试Log输出
     */
    public static void setDebugMode(boolean debug);

例子:

// AIRec SDK调试Log开关,App上线前请关闭Log开关。
    RecAgent.setDebugMode(true);

实例代码摘自Demo工程如下路径:app/src/main/java/com/umeng/airecdemo/MyApp.java

• 设置UserId函数 RecAgent.setUserId(userId);

 /**
     * 设置用户identity。
     * @param userId 非空字符串。
     */
    public static void setUserId(String userId);

例子:

 private static final String BIZ_ID = "bizid1233456";
    // ...
    btSetBizID.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                RecAgent.setUserId("test_user12345");
                RecAgent.setLogin(true);
            }
        });

实例代码摘自Demo工程如下路径:app/src/main/java/com/umeng/airecdemo/MainActivity.java

• 设置UserId函数 RecAgent. setLogin(status);

/**
     * 设置用户登录状态。
     * @param status true: 用户已登录; false: 用户未登录。
     */
    public static void setLogin(boolean status);

例子:

  // ...
    btSetBizID.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                RecAgent.setUserId("test_user12345");
                RecAgent.setLogin(true);
            }
        });

实例代码摘自Demo工程如下路径:app/src/main/java/com/umeng/airecdemo/MainActivity.java

• 推荐事件触发函数 RecAgent.onRecEvent

/**
     * 行为事件类型
     */
    public enum BHV_EVT_TYPE {
        expose,     // 曝光
        click,      // 点击
        cart,       // 加入购物车
        buy,        // 购买
        collect,    // 收藏
        like,       // 点赞
        unlike,     // 点衰
        comment,    // 写评论
        share,      // 分享
        subscribe,  // 订阅
        stay        // 停留
    }
    /**
     * 推荐事件接口函数
     * @param context 接口调用ApplicationContext上下文对象
     * @param traceIdStr TRACE_ID,效果跟踪ID,不能为null,可以使用:RecAgent.TRACEID_ALIBABA 或者 RecAgent.TRACEID_SELFHOLD,也可以自定义其它值
     * @param traceInfo 字符串类型参数,不能为null或者空字符串,效果跟踪信息
     * @param itemId 字符串类型参数,不能为null或者空字符串,物品ID
     * @param itemType 字符串类型参数,不能为null或者空字符串,物品类型
     * @param attribute 用户自定义属性K-V键值对,可以为null,属性K-V值都必须是字符串类型
     * @param bhvType 枚举类型BHV_EVT_TYPE,行为事件类型,不能为null
     * @param bhvValue 字符串类型参数,不能为null或空字符串,
     *                 1. 如果传入的bhvType参数为click,bhvValue 传 1;
     *                 2. 如果传入的bhvType参数为stay,
     *                 则本参数应该可转换为long型值,如果传入参数不能成功转换为long型值,则使用默认值0.
     *                  此时参数含义为停留时长,时间单位:s;
     *                 3. 如果传入的bhvType参数为其它值,则本参数为可选,不指定传入null或空字符串即可。
     * @param bizId 必填否则行为事件不生效
     * @param sceneId 完全自定义
     */
     public static void onRecEvent(Context context,
                                   String traceIdStr,
                                   String traceInfo,
                                   String itemId,
                                   String itemType,
                                   Map<String, String> attribute,
                                   BHV_EVT_TYPE bhvType,
                                   String bhvValue,
                                   String bizId,
                                   String sceneId)

例子:

btRecEvent.setOnClickListener(new View.OnClickListener() {
        @Override
        public void onClick(View v) {
            // 自定义属性
            Map<String, String> args = new HashMap<>();
            args.put("page_id", "12345");
            args.put("module_id", "23456");
            args.put("position_id", "34567");
            RecAgent.onRecEvent(context,
                                   "Alibaba",
                                   "TraceInfo_123",
                                   "item_id_2233",
                                   "item_type_book",args,RecAgent.BHV_EVT_TYPE.click,"12356AA",BIZ_ID,"");
                                           }
                                       });

实例代码摘自Demo工程如下路径:app/src/main/java/com/umeng/airecdemo/MainActivity.java

SDK集成调试

AIRec SDK调试Log开关打开时,SDK会输出相关调试信息。过滤TAG字段为”RecAgent”。