Skip to content

Latest commit

 

History

History
498 lines (377 loc) · 15.3 KB

user-property-upload.md

File metadata and controls

498 lines (377 loc) · 15.3 KB

用户变量上传 API

GrowingIO 支持通过离线的方式批量上传登录用户变量和维度分类变量，配合 SDK 中上传的登录用户 id，可以在不发版的情况下更新用户变量规则。

用户变量上传

1.1 接口

{% api-method method="post" host="https://data.growingio.com/:ai/loginUserId" path="" %} {% api-method-summary %}

{% endapi-method-summary %}

{% api-method-description %}

{% endapi-method-description %}

{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="ai" type="string" required=true %} 项目 id {% endapi-method-parameter %} {% endapi-method-path-parameters %}

{% api-method-headers %} {% api-method-parameter name="Access-Token" type="string" required=true %} public Key {% endapi-method-parameter %}

{% api-method-parameter name="Content-Type" type="string" required=true %} application/json {% endapi-method-parameter %} {% endapi-method-headers %}

{% api-method-query-parameters %} {% api-method-parameter name="auth" type="string" required=true %} 针对每条数据独立生成的认证，计算方式见本文档第二节 {% endapi-method-parameter %} {% endapi-method-query-parameters %}

{% api-method-body-parameters %} {% api-method-parameter name="userProperty1" type="string" required=false %} 在 GrowingIO 系统内定义的用户属性 （如 gender) {% endapi-method-parameter %}

{% api-method-parameter name="userProperty2" type="string" required=false %} 在 GrowingIO 系统内定义的用户属性（如 user_name) {% endapi-method-parameter %}

{% api-method-parameter name="loginUserId" type="string" required=true %} 登录用户 id {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}

{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}

{% endapi-method-response-example-description %}

{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}

Body 内的 userProperty 1-N 为您在 GrowingIO 系统内定义的用户属性的 key，如 user_name, gender 等。支持使用数组的方式一次上传多条数据，一次性最多上传 100 条，body 大小最大限制为 2M。

一次上传一条：

{
    "loginUserId":"1234",
    "user_name":"张三",
    "gender":"男"
}

一次上传多条：

[
{
    "loginUserId":"1234",
    "user_name":"张三",
    "gender":"男"
},
{
    "loginUserId":"1235",
    "user_name":"李四",
    "gender":"女"
}
]

1.2 认证

为防止误传和恶意攻击， GrowingIO 服务器会对收到的每条数据做校验，因此需要在 query 参数中提供校验码。校验码生成代码见下方示例，其中 keyArray 为 loginUserId，一次性上传多条时，使用逗号隔开，如上方示例中，第一条 keyArray 为 1234，第二条为 1234,1235。

Java:

public String authToken(String projectKeyId, String secretKey, String keyArray) throws Exception {
    String message = "ai="+projectKeyId+"&loginUserId="+keyArray;
    Mac hmac = Mac.getInstance("HmacSHA256");
    hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
    byte[] signature = hmac.doFinal(message.getBytes("UTF-8"));
    return Hex.encodeHexString(signature);
}

Scala:

def authToken(projectKeyId: String, secretKey: String, keyArray: String): String = {
  val message = s"ai=$projectKeyId&loginUserId=$keyArray"
  val hmac: Mac = Mac.getInstance("HmacSHA256")
  hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"))
  val signature = hmac.doFinal(message.getBytes("UTF-8"))
  Hex.encodeHexString(signature)
}

Python:

#coding:utf-8 
import hashlib
import hmac

def authToken(projectKeyId,secretKey,keyArray):
    message = ("ai=" + projectKeyId + "&loginUserId=" + keyArray).encode('utf-8')
    signature = hmac.new(bytes(secretKey.encode('utf-8')), bytes(message), digestmod=hashlib.sha256).hexdigest()
    return signature

PHP:

function authToken($projectKeyId, $secretKey, $keyArray)
{
   $message="ai=".$projectKeyId."&loginUserId=".$keyArray;
   return hash_hmac('sha256',$message, $secretKey, false);
}

1.3 旧版本上传接口

之前使用旧版本上传接口的请尽快升级到新版本接口，避免数据上传结果和线上配置出现不一致。

{% api-method method="post" host="https://data.growingio.com/saas/:ai/user" path="" %} {% api-method-summary %}

{% endapi-method-summary %}

{% api-method-description %}

{% endapi-method-description %}

{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="ai" type="string" required=true %} 项目 id {% endapi-method-parameter %} {% endapi-method-path-parameters %}

{% api-method-headers %} {% api-method-parameter name="Access-Token" type="string" required=true %} Public Key {% endapi-method-parameter %} {% endapi-method-headers %}

{% api-method-query-parameters %} {% api-method-parameter name="auth" type="string" required=true %} 针对每条数据独立生成的认证 {% endapi-method-parameter %} {% endapi-method-query-parameters %}

{% api-method-body-parameters %} {% api-method-parameter name="cs2" type="string" required=false %} 用户属性2 {% endapi-method-parameter %}

{% api-method-parameter name="cs1" type="string" required=true %} 登录用户 id {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}

{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}

{% endapi-method-response-example-description %}

{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}

旧版本上传接口使用 cs1-cs20 的方式上传用户属性，对应的签名计算中 keyArray 为1234,1235。加密 Message 为 ai=$projectKeyId&cs=$keyArray

如 Java：

public String authToken(String projectKeyId, String secretKey, String keyArray) throws Exception {
    String message = "ai="+projectKeyId+"&cs="+keyArray;
    Mac hmac = Mac.getInstance("HmacSHA256");
    hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
    byte[] signature = hmac.doFinal(message.getBytes("UTF-8"));
    return Hex.encodeHexString(signature);
}

维度分类上传

2.1 接口

{% api-method method="post" host="https://data.growingio.com/:ai/classification/:variable\_name" path="" %} {% api-method-summary %}

{% endapi-method-summary %}

{% api-method-description %}

{% endapi-method-description %}

{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="ai" type="string" required=true %} 项目 id {% endapi-method-parameter %}

{% api-method-parameter name="variable_name" type="string" required=true %} 用户变量标识符 {% endapi-method-parameter %} {% endapi-method-path-parameters %}

{% api-method-headers %} {% api-method-parameter name="Access-Token" type="string" required=true %} Public Key {% endapi-method-parameter %}

{% api-method-parameter name="Content-Type" type="string" required=true %} application/json {% endapi-method-parameter %} {% endapi-method-headers %}

{% api-method-query-parameters %} {% api-method-parameter name="auth" type="string" required=true %} 针对数据生成的认证，计算方式与上述类似 {% endapi-method-parameter %} {% endapi-method-query-parameters %}

{% api-method-body-parameters %} {% api-method-parameter name="variable_name" type="string" required=true %} 在GrowingIO系统内定义的用户属性，且为需要分类用户变量的标识符（如companyId） {% endapi-method-parameter %}

{% api-method-parameter name="userProperty1" type="string" required=false %} 在GrowingIO系统内定义的用户属性（如companyName） {% endapi-method-parameter %}

{% api-method-parameter name="userProperty2" type="string" required=false %} 在GrowingIO系统内定义的用户属性（如companyClass） {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}

{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}

{% endapi-method-response-example-description %}

{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}

Body 内的 variable_name、userProperty 1-N 为您在 GrowingIO 系统内定义的用户属性的 key。类似用户属性上传，支持是用户数组的方式一次上传多条数据，一次性最多上传 100 条，body 大小最大限制为 2M。

2.2 认证

认证方式与用户属性上传类似，其中 keyArray 为 variable_name 的值，多条使用逗号分隔，如：1234,1235。
加密 Message 为 ai=$projectId&$variable_name=$keyArray （注意variable_name为实际变量名称）。

如 Java：

public String authToken(String projectKeyId, String variableName, String secretKey, String keyArray) throws Exception {
    String message = "ai="+projectKeyId+"&"+variableName+"="+keyArray;
    Mac hmac = Mac.getInstance("HmacSHA256");
    hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
    byte[] signature = hmac.doFinal(message.getBytes("UTF-8"));
    return Hex.encodeHexString(signature);
}

2.3 旧版本上传接口

之前使用旧版本上传接口的请尽快升级到新版本接口，避免数据上传结果和线上配置出现不一致。

{% api-method method="post" host="https://data.growingio.com/saas/:ai/company" path="" %} {% api-method-summary %}

{% endapi-method-summary %}

{% api-method-description %}

{% endapi-method-description %}

{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="ai" type="string" required=true %} 项目 id {% endapi-method-parameter %} {% endapi-method-path-parameters %}

{% api-method-headers %} {% api-method-parameter name="Access-Token" type="string" required=true %} Public Key {% endapi-method-parameter %}

{% api-method-parameter name="Content-Type" type="string" required=true %} application/json {% endapi-method-parameter %} {% endapi-method-headers %}

{% api-method-query-parameters %} {% api-method-parameter name="auth" type="string" required=true %} 针对数据生成的认证，计算方式与上述类似 {% endapi-method-parameter %} {% endapi-method-query-parameters %}

{% api-method-body-parameters %} {% api-method-parameter name="cs2" type="string" required=true %} 用户属性2，且为需要分类用户变量的标识符 {% endapi-method-parameter %}

{% api-method-parameter name="cs3" type="string" required=false %} 用户属性3 {% endapi-method-parameter %}

{% api-method-parameter name="cs4" type="string" required=false %} 用户属性4 {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}

{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}

{% endapi-method-response-example-description %}

{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}

旧版本上传接口使用 cs1-cs20 的方式上传用户属性，对应的签名计算中 keyArray 为 参数 cs2的值，多条用逗号拼接，如：1234,1235。
加密 Message 为 ai=$projectKeyId&cs=$keyArray

如 Java：

public String authToken(String projectKeyId, String secretKey, String keyArray) throws Exception {
    String message = "ai="+projectKeyId+"&cs="+keyArray;
    Mac hmac = Mac.getInstance("HmacSHA256");
    hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
    byte[] signature = hmac.doFinal(message.getBytes("UTF-8"));
    return Hex.encodeHexString(signature);
}

既有登录用户ID上传

含义：客户从登录用户ID的视角认为有一些用户是既有用户，而不是新用户。所有GrowingIO暴露了一个接口来定义某一些登录用户ID为既有用户，并不是新用户。同时，还提供上传登录用户的注册时间，来告诉GrowingIO该用户成为新用户的时间。

3.1 接口

{% api-method method="post" host="https://data.growingio.com/{ai}/user/exist" path="" %} {% api-method-summary %}

{% endapi-method-summary %}

{% api-method-description %}

{% endapi-method-description %}

{% api-method-spec %} {% api-method-request %} {% api-method-path-parameters %} {% api-method-parameter name="ai" type="string" required=true %} 项目 ID {% endapi-method-parameter %} {% endapi-method-path-parameters %}

{% api-method-headers %} {% api-method-parameter name="Content-Type" type="string" required=true %} application/json {% endapi-method-parameter %}

{% api-method-parameter name="Access-Token" type="string" required=true %} 项目公钥 public key {% endapi-method-parameter %} {% endapi-method-headers %}

{% api-method-query-parameters %} {% api-method-parameter name="auth" type="string" required=true %} 针对数据生成的认证，计算方式与上述类似 {% endapi-method-parameter %} {% endapi-method-query-parameters %}

{% api-method-body-parameters %} {% api-method-parameter name="loginUserId" type="array" required=true %} 登录用户ID字符串数组 {% endapi-method-parameter %}

{% api-method-parameter name="registerTime" type="number" required=false %} 上传用户注册的时间戳, 可选 {% endapi-method-parameter %} {% endapi-method-body-parameters %} {% endapi-method-request %}

{% api-method-response %} {% api-method-response-example httpCode=200 %} {% api-method-response-example-description %}

{% endapi-method-response-example-description %}

{% endapi-method-response-example %} {% endapi-method-response %} {% endapi-method-spec %} {% endapi-method %}

上传Body的限制规则与上述其他接口一致，内容示例如下：

{
  "loginUserId": ["abcdef", "bcdefg", ...],
  "registerTime": 1514764800000
}

3.2 认证

auth的计算需要将loginUserId的值拼接成keyArray，多条使用逗号分隔，如上述示例中的keyArray为abcdef,bcdefg。Java代码示例如下：

/**
 * projectKeyId: 项目ID
 * secretKey: 项目私钥
 * keyArray: loginUserId用逗号拼接的字符串
*/ 
public String authToken(String projectKeyId, String secretKey, String keyArray) throws Exception {
    String message = "projectId="+projectKeyId+"&loginUserId="+keyArray;
    Mac hmac = Mac.getInstance("HmacSHA256");
    hmac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
    byte[] signature = hmac.doFinal(message.getBytes("UTF-8"));
    return Hex.encodeHexString(signature);
}