小程序：增加数据分析相关 API

binarywang · binarywang · May 1, 2018 · Apr 26, 2018 · Apr 26, 2018 · Apr 26, 2018
commit 0b37739ceeb4a08b63524cb38f98fe4f2522e064
diff --git a/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaAnalysisService.java b/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaAnalysisService.java
@@ -0,0 +1,145 @@
+package cn.binarywang.wx.miniapp.api;
+
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaRetainInfo;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaSummaryTrend;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaUserPortrait;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaVisitDistribution;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaVisitPage;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaVisitTrend;
+import me.chanjar.weixin.common.exception.WxErrorException;
+
+import java.util.Date;
+import java.util.List;
+
+/**
+ * 小程序数据分析相关接口
+ * 文档：https://mp.weixin.qq.com/debug/wxadoc/dev/api/analysis.html
+ *
+ * @author <a href="https://github.com/charmingoh">Charming</a>
+ * @since 2018-04-28
+ */
+public interface WxMaAnalysisService {
+  String GET_DAILY_SUMMARY_TREND_URL = "https://api.weixin.qq.com/datacube/getweanalysisappiddailysummarytrend";
+  String GET_DAILY_VISIT_TREND_URL = "https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend";
+  String GET_WEEKLY_VISIT_TREND_URL = "https://api.weixin.qq.com/datacube/getweanalysisappidweeklyvisittrend";
+  String GET_MONTHLY_VISIT_TREND_URL = "https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyvisittrend";
+  String GET_VISIT_DISTRIBUTION_URL = "https://api.weixin.qq.com/datacube/getweanalysisappidvisitdistribution";
+  String GET_DAILY_RETAIN_INFO_URL = "https://api.weixin.qq.com/datacube/getweanalysisappiddailyretaininfo";
+  String GET_WEEKLY_RETAIN_INFO_URL = "https://api.weixin.qq.com/datacube/getweanalysisappidweeklyretaininfo";
+  String GET_MONTHLY_RETAIN_INFO_URL = "https://api.weixin.qq.com/datacube/getweanalysisappidmonthlyretaininfo";
+  String GET_VISIT_PAGE_URL = "https://api.weixin.qq.com/datacube/getweanalysisappidvisitpage";
+  String GET_USER_PORTRAIT_URL = "https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait";
+
+  /**
+   * 查询概况趋势
+   * 温馨提示：小程序接口目前只能查询一天的数据，即 beginDate 和 endDate 一样
+   *
+   * @param beginDate 开始日期
+   * @param endDate   结束日期，限定查询1天数据，end_date允许设置的最大值为昨日
+   * @return 概况趋势
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  List<WxMaSummaryTrend> getDailySummaryTrend(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 获取日访问趋势
+   * 温馨提示：小程序接口目前只能查询一天的数据，即 beginDate 和 endDate 一样
+   *
+   * @param beginDate 开始日期
+   * @param endDate   结束日期，限定查询1天数据，end_date允许设置的最大值为昨日
+   * @return 日访问趋势
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  List<WxMaVisitTrend> getDailyVisitTrend(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 获取周访问趋势
+   * 限定查询一个自然周的数据，时间必须按照自然周的方式输入： 如：20170306(周一), 20170312(周日)
+   *
+   * @param beginDate 开始日期，为周一日期
+   * @param endDate   结束日期，为周日日期，限定查询一周数据
+   * @return 周访问趋势（每项数据都是一个自然周汇总）
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  List<WxMaVisitTrend> getWeeklyVisitTrend(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 获取月访问趋势
+   * 限定查询一个自然月的数据，时间必须按照自然月的方式输入： 如：20170201(月初), 20170228(月末)
+   *
+   * @param beginDate 开始日期，为自然月第一天
+   * @param endDate   结束日期，为自然月最后一天，限定查询一个月数据
+   * @return 月访问趋势（每项数据都是一个自然月汇总）
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  List<WxMaVisitTrend> getMonthlyVisitTrend(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 获取访问分布
+   * （此接口目前只能查询一天的数据，即 beginDate 和 endDate 一样）
+   *
+   * @param beginDate 开始日期，为周一日期
+   * @param endDate   结束日期，限定查询1天数据，end_date允许设置的最大值为昨日
+   * @return 访问分布
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  WxMaVisitDistribution getVisitDistribution(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 日留存
+   * （此接口目前只能查询一天的数据，即 beginDate 和 endDate 一样）
+   *
+   * @param beginDate 开始日期，为周一日期
+   * @param endDate   结束日期，限定查询 1 天数据，endDate 允许设置的最大值为昨日
+   * @return 日留存
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  WxMaRetainInfo getDailyRetainInfo(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 周留存
+   * 限定查询一个自然周的数据，时间必须按照自然周的方式输入： 如：20170306(周一), 20170312(周日)
+   *
+   * @param beginDate 开始日期，为周一日期
+   * @param endDate   结束日期，为周日日期，限定查询一周数据
+   * @return 周留存
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  WxMaRetainInfo getWeeklyRetainInfo(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 月留存
+   * 限定查询一个自然月的数据，时间必须按照自然月的方式输入： 如：20170201(月初), 20170228(月末)
+   *
+   * @param beginDate 开始日期，为自然月第一天
+   * @param endDate   结束日期，为自然月最后一天，限定查询一个月数据
+   * @return 月留存
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  WxMaRetainInfo getMonthlyRetainInfo(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 获取访问页面数据
+   * 温馨提示：此接口目前只能查询一天的数据，即 beginDate 和 endDate 一样
+   *
+   * @param beginDate 开始日期
+   * @param endDate   结束日期，限定查询1天数据，end_date允许设置的最大值为昨日
+   * @return 访问页面数据
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  List<WxMaVisitPage> getVisitPage(Date beginDate, Date endDate) throws WxErrorException;
+
+  /**
+   * 获取小程序新增或活跃用户的画像分布数据
+   * 时间范围支持昨天、最近7天、最近30天。
+   * 其中，新增用户数为时间范围内首次访问小程序的去重用户数，
+   * 活跃用户数为时间范围内访问过小程序的去重用户数。
+   * 画像属性包括用户年龄、性别、省份、城市、终端类型、机型。
+   *
+   * @param beginDate 开始日期
+   * @param endDate   结束日期，开始日期与结束日期相差的天数限定为0/6/29，分别表示查询最近1/7/30天数据，end_date允许设置的最大值为昨日
+   * @return 小程序新增或活跃用户的画像分布数据
+   * @throws WxErrorException 获取失败时抛出，具体错误码请看文档
+   */
+  WxMaUserPortrait getUserPortrait(Date beginDate, Date endDate) throws WxErrorException;
+}
diff --git a/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaService.java b/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaService.java
@@ -135,6 +135,13 @@ public interface WxMaService {
    */
   WxMaTemplateService getTemplateService();
 
+  /**
+   * 数据分析相关查询服务
+   *
+   * @return WxMaAnalysisService
+   */
+  WxMaAnalysisService getAnalysisService();
+
   /**
    * 返回代码操作相关的 API
    *

diff --git a/...java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaAnalysisServiceImpl.java b/...java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaAnalysisServiceImpl.java
@@ -0,0 +1,126 @@
+package cn.binarywang.wx.miniapp.api.impl;
+
+import cn.binarywang.wx.miniapp.api.WxMaAnalysisService;
+import cn.binarywang.wx.miniapp.api.WxMaService;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaRetainInfo;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaSummaryTrend;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaUserPortrait;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaVisitDistribution;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaVisitPage;
+import cn.binarywang.wx.miniapp.bean.analysis.WxMaVisitTrend;
+import cn.binarywang.wx.miniapp.util.json.WxMaGsonBuilder;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import com.google.gson.reflect.TypeToken;
+import me.chanjar.weixin.common.exception.WxErrorException;
+import org.apache.commons.lang3.time.DateFormatUtils;
+
+import java.lang.reflect.Type;
+import java.util.Date;
+import java.util.List;
+
+/**
+ * @author <a href="https://github.com/charmingoh">Charming</a>
+ * @since 2018-04-28
+ */
+public class WxMaAnalysisServiceImpl implements WxMaAnalysisService {
+  private static final JsonParser JSON_PARSER = new JsonParser();
+  private WxMaService wxMaService;
+
+  public WxMaAnalysisServiceImpl(WxMaService wxMaService) {
+    this.wxMaService = wxMaService;
+  }
+
+  @Override
+  public List<WxMaSummaryTrend> getDailySummaryTrend(Date beginDate, Date endDate) throws WxErrorException {
+    return getAnalysisResultAsList(GET_DAILY_SUMMARY_TREND_URL, beginDate, endDate,
+      new TypeToken<List<WxMaSummaryTrend>>() {
+      }.getType());
+  }
+
+  @Override
+  public List<WxMaVisitTrend> getDailyVisitTrend(Date beginDate, Date endDate) throws WxErrorException {
+    return getAnalysisResultAsList(GET_DAILY_VISIT_TREND_URL, beginDate, endDate,
+      new TypeToken<List<WxMaVisitTrend>>() {
+      }.getType());
+  }
+
+  @Override
+  public List<WxMaVisitTrend> getWeeklyVisitTrend(Date beginDate, Date endDate) throws WxErrorException {
+    return getAnalysisResultAsList(GET_WEEKLY_VISIT_TREND_URL, beginDate, endDate,
+      new TypeToken<List<WxMaVisitTrend>>() {
+      }.getType());
+  }
+
+  @Override
+  public List<WxMaVisitTrend> getMonthlyVisitTrend(Date beginDate, Date endDate) throws WxErrorException {
+    return getAnalysisResultAsList(GET_MONTHLY_VISIT_TREND_URL, beginDate, endDate,
+      new TypeToken<List<WxMaVisitTrend>>() {
+      }.getType());
+  }
+
+  @Override
+  public WxMaVisitDistribution getVisitDistribution(Date beginDate, Date endDate) throws WxErrorException {
+    String responseContent = this.wxMaService.post(GET_VISIT_DISTRIBUTION_URL, toJson(beginDate, endDate));
+    return WxMaVisitDistribution.fromJson(responseContent);
+  }
+
+  @Override
+  public WxMaRetainInfo getDailyRetainInfo(Date beginDate, Date endDate) throws WxErrorException {
+    return getRetainInfo(beginDate, endDate, GET_DAILY_RETAIN_INFO_URL);
+  }
+
+  @Override
+  public WxMaRetainInfo getWeeklyRetainInfo(Date beginDate, Date endDate) throws WxErrorException {
+    return getRetainInfo(beginDate, endDate, GET_WEEKLY_RETAIN_INFO_URL);
+  }
+
+  @Override
+  public WxMaRetainInfo getMonthlyRetainInfo(Date beginDate, Date endDate) throws WxErrorException {
+    return getRetainInfo(beginDate, endDate, GET_MONTHLY_RETAIN_INFO_URL);
+  }
+
+  @Override
+  public List<WxMaVisitPage> getVisitPage(Date beginDate, Date endDate) throws WxErrorException {
+    return getAnalysisResultAsList(GET_VISIT_PAGE_URL, beginDate, endDate,
+      new TypeToken<List<WxMaVisitPage>>() {
+      }.getType());
+  }
+
+  @Override
+  public WxMaUserPortrait getUserPortrait(Date beginDate, Date endDate) throws WxErrorException {
+    String responseContent = this.wxMaService.post(GET_USER_PORTRAIT_URL, toJson(beginDate, endDate));
+    return WxMaUserPortrait.fromJson(responseContent);
+  }
+
+  private WxMaRetainInfo getRetainInfo(Date beginDate, Date endDate, String url) throws WxErrorException {
+    String responseContent = this.wxMaService.post(url, toJson(beginDate, endDate));
+    return WxMaRetainInfo.fromJson(responseContent);
+  }
+
+  /**
+   * 获取数据分析结果并返回 List，returnType 类型
+   *
+   * @param url        链接
+   * @param returnType 返回的类型
+   * @param <T>        返回的类型
+   * @return List 类型的数据
+   */
+  private <T> List<T> getAnalysisResultAsList(String url, Date beginDate, Date endDate, Type returnType) throws WxErrorException {
+    String responseContent = this.wxMaService.post(url, toJson(beginDate, endDate));
+    JsonObject response = JSON_PARSER.parse(responseContent).getAsJsonObject();
+    boolean hasList = response.has("list");
+    if (hasList) {
+      return WxMaGsonBuilder.create().fromJson(response.getAsJsonArray("list"), returnType);
+    } else {
+      return null;
+    }
+  }
+
+  private static String toJson(Date beginDate, Date endDate) {
+    JsonObject param = new JsonObject();
+    param.addProperty("begin_date", DateFormatUtils.format(beginDate, "yyyyMMdd"));
+    param.addProperty("end_date", DateFormatUtils.format(endDate, "yyyyMMdd"));
+    return param.toString();
+  }
+}
diff --git a/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaServiceImpl.java b/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaServiceImpl.java
@@ -1,5 +1,6 @@
 package cn.binarywang.wx.miniapp.api.impl;
 
+import cn.binarywang.wx.miniapp.api.WxMaAnalysisService;
 import cn.binarywang.wx.miniapp.api.WxMaCodeService;
 import cn.binarywang.wx.miniapp.api.WxMaMediaService;
 import cn.binarywang.wx.miniapp.api.WxMaMsgService;
@@ -52,6 +53,7 @@ public class WxMaServiceImpl implements WxMaService, RequestHttp<CloseableHttpCl
   private WxMaUserService userService = new WxMaUserServiceImpl(this);
   private WxMaQrcodeService qrCodeService = new WxMaQrcodeServiceImpl(this);
   private WxMaTemplateService templateService = new WxMaTemplateServiceImpl(this);
+  private WxMaAnalysisService analysisService = new WxMaAnalysisServiceImpl(this);
   private WxMaCodeService codeService = new WxMaCodeServiceImpl(this);
   private WxMaSettingService settingService = new WxMaSettingServiceImpl(this);
 
@@ -294,6 +296,11 @@ public WxMaTemplateService getTemplateService() {
     return this.templateService;
   }
 
+  @Override
+  public WxMaAnalysisService getAnalysisService() {
+    return this.analysisService;
+  }
+
   @Override
   public WxMaCodeService getCodeService() {
     return this.codeService;

diff --git a/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/analysis/WxMaRetainInfo.java b/weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/analysis/WxMaRetainInfo.java
@@ -0,0 +1,43 @@
+package cn.binarywang.wx.miniapp.bean.analysis;
+
+import cn.binarywang.wx.miniapp.util.json.WxMaGsonBuilder;
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.Map;
+
+/**
+ * 访问留存
+ *
+ * @author <a href="https://github.com/charmingoh">Charming</a>
+ * @since 2018-04-28 14:41
+ */
+@Data
+public class WxMaRetainInfo implements Serializable {
+  private static final long serialVersionUID = 8986403173656848413L;
+  /**
+   * 日留存：日期，yyyyMMdd 格式，如 20170313
+   * 周留存：时间，如"20170306-20170312"
+   * 月留存：时间，如"201702"
+   */
+  @SerializedName(value = "refDate", alternate = "ref_date")
+  private String refDate;
+  /**
+   * 新增用户留存
+   * - key:
+   *  - 日留存：标识，0开始，0表示当天，1表示1天后，依此类推，key取值分别是：0,1,2,3,4,5,6,7,14,30
+   *  - 周留存：标识，0开始，0表示当周，1表示1周后，依此类推，key 取值分别是：0,1,2,3,4
+   *  - 月留存：标识，0开始，0表示当月，1表示1月后，key取值分别是：0,1
+   * - value: key对应日期的新增用户数/活跃用户数（key=0时）或留存用户数（k>0时）
+   */
+  private Map<Integer, Integer> visitUvNew;
+  /**
+   * 活跃用户留存
+   */
+  private Map<Integer, Integer> visitUv;
+
+  public static WxMaRetainInfo fromJson(String json) {
+    return WxMaGsonBuilder.create().fromJson(json, WxMaRetainInfo.class);
+  }
+}
diff --git a/...n-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/analysis/WxMaSummaryTrend.java b/...n-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/analysis/WxMaSummaryTrend.java
@@ -0,0 +1,37 @@
+package cn.binarywang.wx.miniapp.bean.analysis;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+
+import java.io.Serializable;
+
+/**
+ * 小程序概况趋势
+ *
+ * @author <a href="https://github.com/charmingoh">Charming</a>
+ * @since 2018-04-28
+ */
+@Data
+public class WxMaSummaryTrend implements Serializable {
+  private static final long serialVersionUID = 1379688517709317935L;
+  /**
+   * 日期，yyyyMMdd 格式，如 20170313
+   */
+  @SerializedName(value = "refDate", alternate = "ref_date")
+  private String refDate;
+  /**
+   * 累计用户数
+   */
+  @SerializedName(value = "visitTotal", alternate = "visit_total")
+  private Long visitTotal;
+  /**
+   * 转发次数
+   */
+  @SerializedName(value = "sharePv", alternate = "share_pv")
+  private Long sharePv;
+  /**
+   * 转发人数
+   */
+  @SerializedName(value = "shareUv", alternate = "share_uv")
+  private Long shareUv;
+}