友盟+搜索

{{errorMsg}}

简介

    您可以通过Dplus Open API获得项目数据,从而更加灵活地运用这些数据,例如:与网站业务数据结合,计算网站运营的业绩指标。 将数据导入网站管理后台,绘制更加灵活的报表。 对导出的数据进行深度数据分析和数据挖掘。

API使用流程

    根据您对API导出数据的应用,选择适当的API方法和参数。具体请参见 API分类和方法 。     获取api_key和api_Secret,完成API导出的安全认证。 安全认证方法 。     联调接口,对返回数据进行二次加工。

注意:URI里面的所有参数值都需要经过URL Encode

API分类和方法

细分接口

URI: https://udplusapi.umeng.com/segmentation

参数名 是否必填 说明
data_source 数据源
event_name 事件名称,指明返回哪个事件的数据。这里只能指定单个事件,不支持事件数组。例如event_name=资源下载。
from_date 事件统计的开始日期(包含该日期),格式为yyyy-mm-dd,例如from_date=2015-03-01。
to_date 事件统计的结束日期(包含该日期),格式为yyyy-mm-dd,to_date=2015-03-31。
field 需要数值计算的字段名称,
group_by 将满足条件事件集合按照on指定的属性进行细分;当on为数组时,将按照数组的每一个属性依次细分。例如on=browser,region,city代表,将统计结果先按照browser细分,然后再在同一browser下、按照region细分,最后再在同一browser、同一region下、按照city细分。
where 对指定的事件进行筛选过滤。详细说明请参见过滤条件语法规则。过滤条件语法规则

示例

    小王负责某资源下载站的运营推广。他通过Dplus采集跟踪网站资源的下载情况:当用户点击下载时,触发并发送“资源下载”事件;事件包含一个数值型属性“消耗积分”,用来表示本次下载消耗的用户积分值。     通过Dplus Open API提供的不同方法,小王可以获得需要的各种数据:


例 1:获得访客3月份的总计下载量

参数:

参数名 参数值
event_name 资源下载
from_date 2015-03-01
to_date 2015-03-31
field count(token)

返回格式:

{
  "message" : "ok",
  "data" : [
    690858
  ],
  "code" : 200
}

示例详解

  • event_name=资源下载表示获取名为“资源下载”的事件统计数据。
  • from_date=2015-03-01&to_date=2015-03-31表示统计的是从2015-03-01到2015-03-31这31天的数据。
  • 无group_by参数,则返回总计数据,即“资源下载”事件3月份一共发生70542次。

例 2:获得访客3月份的总计下载量、下载次数、及人均下载次数

参数:

参数名 参数值
event_name 资源下载
from_date 2015-03-01
to_date 2015-03-31
field all

返回格式

{
  "message" : "ok",
  "data" : [
    690858,
    122782,
    5
  ],
  "code" : 200
}

示例详解:

  • event_name、from_date、to_date的说明见 例 1。
  • type=all表示返回结果 [ 690858, 122782, 5 ] 分别为事件“资源下载”在3月份的总计发生次数、总人数和人均下载次数。

例 3:获得不同城市的访客3月份的下载量

参数:

参数名 参数值
event_name 资源下载
from_date 2015-03-01
to_date 2015-03-31
field count(token)
group_by city

返回格式:

{
  "message" : "ok",
  "data" : {
    "连云港市" : [
      2215
    ],
    "贵阳市" : [
      2619
    ],
    "长春市" : [
      2468
    ],
    ......
  },
  "code" : 200
}

示例详解:

  • event_name、from_date、to_date的说明见 例 1。
  • on=city表示按城市统计“资源下载”事件,即3月份里,北京用户总计下载了4977次,深圳用户总计下载了 3846次,广州用户总计下载了3206次……

例 4:获得不同城市的访客3月份里每天的下载量

参数:

参数名 参数值
event_name 资源下载
from_date 2015-03-01
to_date 2015-03-31
field count(token)
group_by city,date

返回格式:

{
  "message" : "ok",
  "data" : {
    "长春市" : {
      "2015-03-01" : [
        2468
      ],
      "2015-03-02" : [
        2281
      ],
      ....
    },
    "贵阳市" : {
      "2015-03-02" : [
        2619
      ],
      "2015-03-02" : [
        135
      ]
    },
    .....
  },
  "code" : 200
}

示例详解:

  • event_name、from_date、to_date的说明见 例 1。
  • on=city,date表示对事件“下载资源”的统计,先按城市进行细分,再对每个城市按照日期进行细分。即北京用户3月31日下载748次,3月30日下载713次……;上海用户3月27日下载422次,3月30日下载299次……

注意:

  • 数据返回结果总是按事件发生次数降序排列。
  • 当返回结果为多维数组时,从外层维度到内层维度,依次按照各维度内的数组元素大小(事件发生次数)降序排序。例如外层维度为city、内层维度为date时,返回的多维数组中外层按各城市的事件发生次数降序排列(北京市、上海市、……),内层按各城市每日的事件发生次数降序排列(北京市:2015-03-31、2015-03-30、……;上海市:2015-03-27、2015-03-30、……)
  • 如果某项的统计结果为0,则该项不出现在返回数组中。例如”铁岭市”只返回了3月31日一天的数据,说明该市其它天的数据为0。

例 5:获得访客3月15日这天各小时的下载量

参数:

参数名 参数值
event_name 资源下载
from_date 2015-03-15
to_date 2015-03-15
field count(token)
group_by hour

返回格式:

{
  "message" : "ok",
  "data" : {
    "2015-03-15 10" : [
      29703
    ],
    "2015-03-15 20" : [
      71388
    ],
    "2015-03-15 13" : [
      34856
    ],
    "2015-03-15 21" : [
      66957
    ]
  },
  "code" : 200
}

示例详解:

  • eventname、fromdate、to_date的说明见 例 1。
  • on=hour表示获得3月15日这天各个小时内的用户下载次数。

例 6:获得访客3月份下载资源消耗的总积分

参数名 参数值
event_name 资源下载
from_date 2015-03-01
to_date 2015-03-31
field sum(消耗积分)

返回格式:

 {
  "message" : "ok",
  "data" : [
    2147483647
  ],
  "code" : 200
}

示例详解:

  • eventname、fromdate、to_date的说明见 例 1。
  • type=sum&metrics=消耗积分表示对3月份用户“下载资源”消耗的积分进行加和。

例 7:获得北、上、广、深的用户3月份的总计下载量

参数:

参数名 参数值
event_name 资源下载
from_date 2015-03-01
to_date 2015-03-31
field count(token)
where city in ('北京市','上海市','广州市','深圳市')

返回格式:

{
  "message" : "ok",
  "data" : [
    6722,
    1432,
    5532,
    8562
  ],
  "code" : 200
}

示例详解:

  • event_name、from_date、to_date的说明见 例 1。
  • where=city in ('北京市','上海市','广州市','深圳市') 表示只计算北京、上海、广州、深圳的用户下载量。

基础接口

 数据源

URI: https://udplusapi.umeng.com/common/get-data-source 描述: 获取一个项目下所有数据源列表

参数名 是否必须 类型 描述
limit integer 最大返回条数。默认最大条数为255。

示例:     小王负责某电商APP的运营推广。他通过Dplus分析不同数据源下用户不同的行为。

参数:

参数名 参数值
limit 255

返回格式:

{
  "message" : "ok",
  "data" : [
    {
      "key" : "547d77defd98c581a4000c49",
      "type" : "app"
    },
    {
      "key" : "5805eb05e0f55a84570035dd",
      "type" : "app"
    },
    {
      "key" : "50e26c315270156df0000031",
      "type" : "app"
    },
    {
      "key" : "56b169bde0f55a94370002b6",
      "type" : "app"
    },
    {
      "key" : "582d6dfc8f4a9d643c000457",
      "type" : "app"
    }
  ],
  "code" : 200
}

事件

URI: https://udplusapi.umeng.com/common/get-event 描述: 获取一个项目下所有事件的名称列表:事件名按事件的最新发生时间,由新到旧排序。

参数名 是否必须 类型 描述
data_source string 数据源,数据源的key用逗号(,)分割,缺省值为所有数据源
limit integer 最大返回条数。默认最大条数为255。

示例: 小王负责某电商APP的运营推广。他通过Dplus跟踪用户使用APP的各种行为,例如:启动APP、注册、登录、浏览商品、加入购物车、提交订单、购买成功等。 通过Dplus提供的事件names方法,小王可以获得采集到的所有事件。

参数

参数名 参数值
limit 255

返回格式:

{
  "message" : "ok",
  "data" : [
    {
      "key" : "播放频道",
      "name" : "播放频道"
    },
    {
      "key" : "弹出点播推荐海报",
      "name" : "弹出点播推荐海报"
    },
    {
      "key" : "加载直播广告",
      "name" : "加载直播广告"
    },
    {
      "key" : "频道列表-进入分类",
      "name" : "频道列表-进入分类"
    },
    {
      "key" : "搜台菜单-耗时",
      "name" : "搜台菜单-耗时"
    }
  ],
  "code" : 200
}

事件属性

URI: https://udplusapi.umeng.com/common/get-properties 描述: 获取一个事件包含的所有属性。事件属性分为系统默认属性和自定义属性,返回结果中,标为true的属性为系统默认属性,标为false的属性为自定义属性。

参数名 是否必须 类型 描述
data_source string 数据源,数据源的key用逗号(,)分割,缺省值为所有数据源
event_name string 指定要获得哪个事件的全部属性名;注意是单一事件名,而不是事件数组,例如event_name=登录。
limit integer 最大返回条数。默认最大条数为255。

示例: 为了分析用户购买商品的种类、数量、金额,以及购买时的付款方式,小王在采集APP数据时,将这些内容定义为事件“购买成功”的不同属性。 通过Dplus提供的事件属性names方法,小王可以获得“购买”事件包含的所有属性。

参数名 参数值
event_name 购买成功

返回格式:

{
  "message" : "ok",
  "data" : [
    {
      "type" : [
        "string"
      ],
      "key" : "region",
      "name" : "region",
      "category" : "sys",
      "hide" : 0
    },
    {
      "type" : [
        "string"
      ],
      "key" : "utm_medium",
      "name" : "utm_medium",
      "category" : "sys",
      "hide" : 0
    },
    {
      "type" : [
        "number"
      ],
      "key" : "initial_view_time",
      "name" : "initial_view_time",
      "category" : "sys",
      "hide" : 0
    },
  ],
  "code" : 200
}

事件属性的值

URI: https://udplusapi.umeng.com/common/get-properties-value

描述: 获取一个项目下所有事件的名称列表:事件名按事件的最新发生时间,由新到旧排序。

参数名 是否必须 类型 描述
data_source string 数据源,数据源的key用逗号(,)分割,缺省值为所有数据源
event_name string 指定要获得哪个事件的全部属性名;注意是单一事件名,而不是事件数组,例如event_name=登录。
properties_name string 事件属性
limit integer 最大返回条数。默认最大条数为255。

示例: 小王负责某电商APP的运营推广。他通过Dplus跟踪用户使用APP的各种行为,例如:启动APP、注册、登录、浏览商品、加入购物车、提交订单、购买成功等。 通过Dplus提供的事件names方法,小王可以获得采集到的所有事件。

返回格式:

{
  "message" : "ok",
  "data" : [
    {
      "name" : "云视听极光"
    },
    {
      "name" : "电视猫\/腾讯视频"
    },
    {
      "name" : "银河·奇异果"
    },
    {
      "name" : "银河·奇异果\/CIBN合一影视\/电视猫\/CIBN"
    },
    {
      "name" : "电视猫"
    },
    {
      "name" : "腾讯视频\/银河·奇异果\/电视猫\/CIBN"
    },
    {
      "name" : "腾讯视频\/银河·奇异果\/电视猫\/CIBN合一影视\/CIBN"
    },
    {
      "name" : "腾讯视频"
    },
    {
      "name" : "腾讯视频\/银河·奇异果\/电视猫\/优酷TV版\/CIBN"
    },
    {
      "name" : "银河·奇异果\/云视听极光\/电视猫"
    }
  ],
  "code" : 200
}

错误编码

所有接口均返回code字段,code可以判断接口是否正确返回数据,code对应关系表如下:

编码 说明
200 正确返回
403 api_key或api_secret不正确,或者其他原因造成的验证失败
500 计算错误,一般为传递参数错误造成

安全认证

image.png

参数:

  • api_key – 用来指明获取哪个项目的API数据,一个项目对应一个api_key,可在【项目管理-API导出】面板中获得。
  • api_secret – 项目的API导出密钥(请务必保密),一个项目对应一个api_secret,可在【项目管理-API导出】面板中获得。
  • sign – 方法调用的数字签名,由该项目的api_key、api_secret以及方法调用的其它参数加密生成。
  • system_time – Unix时间戳(单位:秒),表示当前API的请求时间。

1、登录Dplus > 进入【项目信息】 > 选择您要获取数据的项目 > 打开“Open API”面板 > API Key和API Secret即为该项目Open API的安全认证参数:

image.png

2、设置system_time:system_time表示发出该请求的Unix时间戳(单位:秒)。

3、计算API请求的数字签名:

  • 1)将除sign外的所有参数(包括API方法的全部常规参数、api_key、systemtime,但不包含api_secret)按主键(ASCII码)进行排序;

  • 2)将1中排好序的参数,先对主键和值分别进行URL Encode ,再用“&”进行连接;

  • 3)将2)的结果加上api_secret进行HASH-SHA256算法签名,加密结果即为sign的值。

4、最后,将sign也作为该API的请求参数,与其它参数(指第3步中URL Encode之后的结果,包括api_key、system_time)一起构造出最终URI。

完整示例

获得北京和上海用户3月下旬各天的下载次数和人数。

设置参数

参数名 参数值
event_name 资源下载
from_date 2015-03-21
to_date 2015-03-31
group_by date
field all
where city in ('北京市','上海市')

安全认证

  1. 1.获取API Key和API Secret:在该项目管理界面的Open API面板中获取这两个参数。

  2. 2.设置system_time:假设system_time=1430297858。

  3. 3.用代码实现数字签名的计算:例如您的服务器开发语言是PHP,则可通过以下代码计算sign的值。

代码

  ksort($params);
  $sign = hash("sha256",http_build_query($params).$api_secret);

因此计算出签名sign=ca4edb4a8beb3d3ab82aac3676bc52f7b176b1c8

  1. 4. 构造URL:将第3步中URL Encode后的$args与签名sign一起构造出最终URI。

https://udplus.umeng.com/oepnapi/segmentation?api_key=*****&expire=300&event_name=%E8%B5%84%E6%BA%90%E4%B8%8B%E8%BD%BD&from_date=2015-03-21&to_date=2015-03-31&type=all&on=ZGF0ZQ%3D%3D&where=Y2l0eSBpbiAoJ%2BWMl%2BS6rOW4gicsJ%2BS4iua1t%2BW4gicp&systemtime=1430297858&sign=ca4edb4a8beb3d3ab82aac3676bc52f7b176b1c8