文档

事件管理

更新时间:

在创建行为事件触发的自动化营销任务前,需要定义事件,并实现上报事件。本文对事件自定义、事件管理操作,以及事件上报方法进行说明。

事件分为两类:

  • 自定义事件:

    顾名思义,自定义事件需要由您自行定义,自行实现事件上报。

    支持通过以下渠道上报自定义事件:

    • 您的一方应用:APP、小程序、网页(含H5页面)

    • 第三方系统应用

    例如:将用户在您的H5页面中点击某个按钮、购买某个产品等动作作为一个事件,上报至Quick Audience。

    不同的渠道有两种方法可以上报事件:

    • 适用于APP、小程序、网页、第三方系统:一方应用或第三方系统通过加入脚本,将应用自行采集的log日志转化为标准的MQ事件模型,并将其上报到Quick Audience,具体方法请参见上报事件

    • 适用于APP、小程序、网页:Quick Audience支持对接阿里云用户行为洞察分析平台什么是Quick Tracking,一方应用可以利用Quick Tracking提供的SDK实现事件采集上报,具体方法请参见数据采集接口

  • 系统默认事件:

    系统已预定义社交互动等部分功能模块涉及的系统默认事件,直接由系统对接对应的功能模块,自动上报。

    说明
    • 使用社交互动事件的前提是:已购买社交互动功能包,社交互动模块已绑定微信公众号,且与用户营销模块绑定的微信公众号为同一公众号。

    • 支持组织管理员、空间管理员,以及具有“社交互动-客户运营”或“社交互动-公众号运营”角色的成员使用社交互动事件。

自定义事件

操作步骤:

  1. 选择工作空间>配置管理>自动化营销>事件管理,进入事件列表页面。image

  2. 单击右上角新建事件,弹出新建事件对话框。

  3. 在弹出的对话框中,配置以下参数:1453

    参数

    说明

    应用类型

    选择事件上报渠道的应用类型,支持:

    • APP

    • 小程序

    • Web:网页,含H5页面

    • 第三方系统

    是否Quick Tracking采集

    对于非第三方系统的事件上报渠道,选择是否使用了Quick Tracking采集。

    平台类型

    对于使用了Quick Tracking采集的APP小程序,选择您在数据采集接口配置渠道时已为渠道指定的平台类型。

    渠道名称

    • 对于未使用Quick Tracking采集的渠道,从下拉列表选择渠道名称。

      单击下拉列表中的添加渠道名称、下拉列表右侧的编辑渠道名称,可分别新建、编辑渠道名称。具体操作,请参见下面的添加渠道名称子步骤。

    • 对于使用了Quick Tracking采集的渠道,选择您在数据采集接口配置渠道时设置的渠道名称。

    事件编码

    输入或选择事件编码。由埋点开发人员定义事件编码,用于唯一标识一个事件。

    事件名称

    输入事件名称。

    事件属性

    添加事件时,需要存储的附加信息可以用事件属性进行存储。例如:事件为“成功购买理财产品”,可添加“理财产品类型”为事件属性。

    单击添加事件属性,可增加一行事件属性。

    单击移除,可移除对应的事件属性。

    属性类型

    • 对于使用了Quick Tracking采集的渠道,选择事件属性的类型:

      • 事件属性:默认选择事件属性,为仅用于当前事件的属性。

      • 全局属性:若选择全局属性,该属性设置一次性后,将在同一个渠道的所有事件中都自动添加,如同一个渠道的所有事件中都携带登录用户ID。

    • 对于未使用Quick Tracking采集的渠道,无属性类型选项,均为仅用于当前事件的属性,无全局属性。

    事件属性数据类型

    选择事件属性的数据类型为文本型或数值型。

    事件扩展属性ID

    输入事件扩展属性ID。

    由埋点开发人员定义属性ID,用于存储采集事件的附属信息,如app采集事件为“购买商品”,属性名称可为“商品ID”,属性ID可对应“item_id”。

    事件扩展属性名称

    输入事件扩展属性名称。

    • 添加渠道名称:对于未使用Quick Tracking采集的渠道,若单击添加渠道名称,在弹窗中输入渠道名称、APP_KEY,其中APP_KEY可以唯一标识一个渠道,一般为采集平台上定义的appkey。34253

    • 编辑渠道名称:对于未使用Quick Tracking采集的渠道,若单击编辑渠道名称,出现如下图所示的弹窗。

      • 单击编辑,可修改渠道名称。

      • 若渠道下无事件,单击删除,可删除该渠道的记录。

      26
  4. 单击确认,完成新建事件。

管理事件

事件列表如下图所示。16

说明

列表中显示的三种事件类型:

  • Quick Tracking采集:使用了Quick Tracking采集的自定义事件。

  • 自定义事件:未使用Quick Tracking采集的自定义事件。

  • 系统默认事件:渠道名称将显示为事件对接的功能模块,如社交互动。

您可对事件进行以下管理操作:

  • 搜索:页面右上角支持通过名称或事件编码搜索。

  • 筛选:页面右上角支持筛选指定渠道的事件。

  • 编辑:单击自定义事件对应的编辑,可编辑事件。支持修改事件名称、事件扩展属性名称,以及添加事件属性,不支持修改其他参数或删除事件属性。具体操作与新建事件时相同。

  • 删除:单击自定义事件对应的删除,可删除未被自动化营销任务使用的事件。如事件已被使用,则不可删除。

上报事件

若您不通过Quick Tracking采集数据,则一方应用或第三方系统的研发人员需要编写脚本,将应用自行采集的log日志转化为标准的MQ事件模型,并将其上报到Quick Audience。事件、用户信息上报链路如下图所示。37

事件上报需要安装阿里云提供的Java SDK,使用行为事件消息上报接口、用户身份标识上报接口。说明如下:

使用准备

  • 安装Java SDK

    1. 安装阿里云Java核心库,请参见安装Alibaba Cloud SDK for Java

      说明

      SDK使用说明,请参见Java示例

    2. 安装QuickAudience Java SDK。打开Aliyun Java SDK QuickAudience Public,下载并安装QuickAudience Java SDK。

    3. 在项目目录下的pom.xml文件中,添加Maven依赖。添加依赖后,Maven项目管理工具会自动下载相关JAR包。

      <!--引入阿里云Core 包-->
      <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <version>4.5.2</version>
      </dependency>
      
      <!--引入QuickAudience 阿里云SDK-->
      <!-- https://mvnrepository.com/artifact/com.aliyun/aliyun-java-sdk-retailadvqa-public -->
      <dependency>
          <groupId>com.aliyun</groupId>
          <artifactId>aliyun-java-sdk-retailadvqa-public</artifactId>
          <version>3.3.16</version>
      </dependency>
  • 接口通用入参

    参数

    含义

    必填

    示例

    accessId

    QA实例ID,调用方识别码

    retailadvqa-cn-xxxxxxxxx

    organizationId

    QA组织ID

    56621289-820e-433a-9947-xxxxxxxxx

    • accessId:请使用购买QA的主账号进入订单列表,单击QA(智能用户增长)订单对应的详情,进入订单详情页面获取实例名称。4356789

    • organizationId:请通过浏览器的开发者工具,在登录QA时获取,,如下图所示。image.png

  • OpenAPI Endpoint列表

    地域

    地域

    Endpoint

    cn-shanghai

    上海

    quicka-public.cn-shanghai.aliyuncs.com

    cn-shenzhen

    深圳

    quicka-public.cn-shenzhen.aliyuncs.com

    cn-zhangjiakou

    张家口

    quicka-public.cn-zhangjiakou.aliyuncs.com

行为事件消息上报接口

  • 接口入参

    参数

    含义

    参数类型

    必填

    示例

    eventMessageModelListStr

    行为事件消息体列表

    String

    [  {  "organizationId": "组织ID,获取方法见接口通用入参",  "workspaceId": "空间ID,可在空间管理获取",  "customerId": "客户ID",  "eventSourceCode": "事件渠道编码",  "eventCode": "事件编码",  "eventTime": 1651114368518,  "extendAttributes": {  "事件属性": "事件属性值",  "outBizId": "唯一业务ID,必填"  },  "customerIdList": [  {  "customerId": "xxxxxxxxx",  "idMapping": "mobile"  },  {  "customerId": "xxxxx@alibaba.com",  "idMapping": "email"  }  ],  "v": 1  } ]

  • 接口出参

    参数

    含义

    参数类型

    示例

    success

    接口调用成功与否

    Boolean

    true

    errorCode

    错误码:接口调用失败时

    String

    ES0110000002

    errorDesc

    错误信息:接口调用失败时

    String

    鉴权失败!

    traceId

    请求ID:便于问题跟踪

    String

  • 接入Demo

    import com.alibaba.fastjson.JSONObject;
    import com.aliyuncs.DefaultAcsClient;
    import com.aliyuncs.IAcsClient;
    import com.aliyuncs.exceptions.ClientException;
    import com.aliyuncs.profile.DefaultProfile;
    import com.aliyuncs.retailadvqa_public.model.v20200515.RecieveEventMessageRequest;
    import com.aliyuncs.retailadvqa_public.model.v20200515.RecieveEventMessageResponse;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    import java.util.Arrays;
    import java.util.HashMap;
    import java.util.Map;
    
    /**
     * 上报事件消息
    */
    public class RecieveEventMessage {
        // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
        // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
        // 本示例以将AccessKey 和 AccessKeySecret 保存在环境变量为例说明。
        // 保存环境变量的方法参考如下:
        // Linux和macOS系统配置方法
        // 执行以下命令:
        // export SCA_AK_ENV=<access_key_id>
        // export SCA_SK_ENV=<access_key_secret>
        // <access_key_id>替换为已准备好的AccessKey ID,<access_key_secret>替换为AccessKey Secret。
        static String accessKey = System.getenv("SCA_AK_ENV");
        static String accessSecret = System.getenv("SCA_SK_ENV");
        static String regionId = "cn-shanghai";
        static String product = "retailadvqa-public";
        static String endpointUrl = "quicka-public.cn-shanghai.aliyuncs.com";
    
        static IAcsClient client = null;
        static {
            DefaultProfile profile =
                    DefaultProfile.getProfile(
                            regionId,          // 地域ID
                            accessKey,         // RAM账号的AccessKeyID
                            accessSecret       // RAM账号AccessKeySecret
                    );
            try {
                DefaultProfile.addEndpoint(
                        regionId,
                        product,
                        endpointUrl
                );
            } catch (Exception e) { }
            client= new DefaultAcsClient(profile);
        }
    
        public static void recieveEventMessage() throws ClientException {
            RecieveEventMessageRequest eventMessageRequest = new RecieveEventMessageRequest();
            eventMessageRequest.setAccessId("retailadvqa-xx-xxxxxxxxx");
            eventMessageRequest.setOrganizationId("56621289-820e-433a-9947-xxxxxxxxx");
    
    
            EventMessageModel messageModel = new EventMessageModel();
            messageModel.setOrganizationId(eventMessageRequest.getOrganizationId());
            messageModel.setCustomerId("customer001");
            messageModel.setEventSourceCode("eventsource001");
            messageModel.setEventCode("event001");
            messageModel.setEventTime(System.currentTimeMillis());
            Map<String, String> extendAttributes = new HashMap<>();
            extendAttributes.put("key1", "value1");
            extendAttributes.put("key2", "123456");
            messageModel.setExtendAttributes(extendAttributes);
    
            // 批量上报接口,批量限制100。
            eventMessageRequest.setEventMessageModelListStr(JSONObject.toJSONString(Arrays.asList(messageModel)));
            System.out.println(JSONObject.toJSONString(Arrays.asList(messageModel)));
    
            RecieveEventMessageResponse recieveEventMessageResponse = client.getAcsResponse(eventMessageRequest);
            System.out.println("result = " + JSONObject.toJSONString(recieveEventMessageResponse));
        }
    
        public static void main(String... args) throws ClientException {
            recieveEventMessage();
        }
    
        @Data
        public static class EventMessageModel {
    
            @ApiModelProperty("组织Id")
            String organizationId;
    
            @ApiModelProperty(required = true, value = "用户/粉丝Id")
            String customerId;
    
            @ApiModelProperty("app_key。如果事件消息中没有app_key,自动化营销任务计算将不受渠道限制")
            String eventSourceCode;
    
            @ApiModelProperty(required = true, value = "事件编码")
            String eventCode;
    
            @ApiModelProperty(required = true, value = "事件实际发生的时间")
            Long eventTime;
    
            @ApiModelProperty("事件扩展属性ID和对应的值")
            Map<String, String> extendAttributes = new HashMap<>();
    
            @ApiModelProperty("事件消息模型版本号")
            Integer v = 1;
        }
    }

用户身份标识上报接口

  • 接口入参

    参数

    含义

    参数类型

    必填

    示例

    customerMessageModelListStr

    用户身份标识消息体列表

    String

    [{"customerId":"customer001","customerIdList":[{"customerId":"13888888888","idMapping":"mobile"}],"organizationId":"56621289-820e-433a-9947-xxxxxxxxx","v":1}]

  • 接口出参

    参数

    含义

    参数类型

    示例

    success

    接口调用成功与否

    Boolean

    true

    errorCode

    错误码:接口调用失败时

    String

    ES0110000002

    errorDesc

    错误信息:接口调用失败时

    String

    鉴权失败!

    traceId

    请求ID:便于问题跟踪

    String

  • 接入Demo

    import com.alibaba.fastjson.JSONObject;
    import com.aliyuncs.DefaultAcsClient;
    import com.aliyuncs.IAcsClient;
    import com.aliyuncs.exceptions.ClientException;
    import com.aliyuncs.profile.DefaultProfile;
    import com.aliyuncs.retailadvqa_public.model.v20200515.RecieveUserMessageRequest;
    import com.aliyuncs.retailadvqa_public.model.v20200515.RecieveUserMessageResponse;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    import java.util.Arrays;
    import java.util.List;
    
    /**
     * 上报用户身份标识
     */
    public class RecieveCustomerMessage {
        // 阿里云账号AccessKey拥有所有API的访问权限,建议您使用RAM用户进行API访问或日常运维。
        // 强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。
        // 本示例以将AccessKey 和 AccessKeySecret 保存在环境变量为例说明。
        // 保存环境变量的方法参考如下:
        // Linux和macOS系统配置方法
        // 执行以下命令:
        // export SCA_AK_ENV=<access_key_id>
        // export SCA_SK_ENV=<access_key_secret>
        // <access_key_id>替换为已准备好的AccessKey ID,<access_key_secret>替换为AccessKey Secret。
        static String accessKey = System.getenv("SCA_AK_ENV");
        static String accessSecret = System.getenv("SCA_SK_ENV");
        static String regionId = "cn-shanghai";
        static String product = "retailadvqa-public";
        static String endpointUrl = "quicka-public.cn-shanghai.aliyuncs.com";
    
        static IAcsClient client = null;
        static {
            DefaultProfile profile =
                    DefaultProfile.getProfile(
                            regionId,          // 地域ID
                            accessKey,         // RAM账号的AccessKeyID
                            accessSecret       // RAM账号AccessKeySecret
                    );
            try {
                DefaultProfile.addEndpoint(
                        regionId,
                        product,
                        endpointUrl
                );
            } catch (Exception e) { }
            client= new DefaultAcsClient(profile);
        }
    
        public static void recieveCustomerMessage() throws ClientException {
            RecieveUserMessageRequest recieveUserMessageRequest = new RecieveUserMessageRequest();
            recieveUserMessageRequest.setAccessId("retailadvqa-xx-xxxxxxxxx");
            recieveUserMessageRequest.setOrganizationId("56621289-820e-433a-9947-xxxxxxxxx");
            CustomerMessageModel customerMessageModel = new CustomerMessageModel();
            customerMessageModel.setOrganizationId(recieveUserMessageRequest.getOrganizationId());
            customerMessageModel.setCustomerId("customer001");
            CustomerIdModel idModel = new CustomerIdModel();
            idModel.setCustomerId("13888888888");
            idModel.setIdMapping("mobile");
            customerMessageModel.setCustomerIdList(Arrays.asList(idModel));
    
            // 消息上报,批量限制100。
            recieveUserMessageRequest.setCustomerMessageModelListStr(JSONObject.toJSONString(Arrays.asList(customerMessageModel)));
            System.out.println(JSONObject.toJSONString(Arrays.asList(customerMessageModel)));
            RecieveUserMessageResponse recieveUserMessageResponse = client.getAcsResponse(recieveUserMessageRequest);
            System.out.println("result = " + JSONObject.toJSONString(recieveUserMessageResponse));
        }
    
        public static void main(String... args) throws ClientException {
            recieveCustomerMessage();
        }
    
        @Data
        public static class CustomerMessageModel {
    
            @ApiModelProperty("组织Id")
            String organizationId;
    
            @ApiModelProperty(required = true, value = "用户/粉丝Id")
            String customerId;
    
            @ApiModelProperty(required = true, value = "用户身份标识ID信息:如 idfa、imei、mobile")
            List<CustomerIdModel> customerIdList;
    
    
            @ApiModelProperty("用户身份标识消息模型版本号")
            Integer v = 1;
        }
    
        @Data
        public static class CustomerIdModel {
    
            @ApiModelProperty(required = true, value = "用户/粉丝Id")
            String customerId;
    
            /**
             目前支持如下用户ID类型:
             1)oneid:客户自定义ID类型,不映射数据银行的类型
             2)email:电子邮件
             3)mobile:手机号
             4)taobao_id:淘宝ID
             5)taobao_nick:淘宝昵称
             6)imei:手机IMEI
             7)idfa:手机IDFA
             8)mac_org:设备MAC地址
             9)weibo_id_org:微博ID
             10)alipay_id:支付宝ID
             11)open_id:微信OpenID
             12) union_id:微信UnionID
             */
            @ApiModelProperty(required = true, value = "用户Id类型")
            String idMapping;
        }
    }