DataFinder为您提供服务端-Java SDK，用来简化服务端埋点的复杂度。通过使用SDK，您可以仅仅关注埋点方案而不需要关注具体的上报细节。本文为您介绍Java SDK的集成流程和埋点配置示例。

下图为您概要介绍 SDK 集成相关文档的组织思路，您可参考以下导读示意图了解文档结构，查阅对应文档完成 集成操作。

步骤1（可选）：创建埋点需求/录入自定义埋点 #

完成埋点规划后，建议您根据规划将埋点需求创建再 DataFinder 的需求管理页面，并将自定义埋点先录入 DataFinder 完成自定义埋点在 DataFinder 元数据的入库。

• 埋点需求管理：您可以通过 DataFinder 的埋点需求管理功能来管理埋点需求，后续可在埋点需求管理页面中持续维护和管理需求，提高管理效率。创建埋点需求管理的操作请参见需求管理。
• 自定义埋点录入：您可以根据埋点规划，先将自定义埋点创建录入至 DataFinder 的元数据，操作详情请参见新增事件、新增事件属性、新增用户属性。

步骤2：获取APPID/APP Key #

进行SDK集成前，您需要先获取在DataFinder上创建应用时，DataFinder生成的应用标识（APPID 或 APP Key），用于后续SDK集成时配置。
在开始集成前，首先需要在集团中拥有一个应用，进行 SDK 集成前，您需要获取对应应用的 appid 信息。

• SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见项目管理。
  

• SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用 ID」中可查看您的 appid，详情请参见应用列表。
  

• 私有化场景，同SaaS-云原生场景

步骤3：获取数据上送地址 #

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址，如果上报地址设置错误，后续会导致您无法查询到上报的数据。

SaaS-云原生 & SaaS-非云原生 #

私有化环境 #

私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

了解上报模式 #

增长分析的 SDK 支持多种上报模式：HTTP、KAFKA，您可按需选择使用合适的模式，对比介绍如下。

查看示例 Demo #

前往Git查看示例demo：示例代码。示例说明如下：

step1：添加依赖 #

获取SDK最新版本 #

建议您集成最新版本的SDK。当前SDK已经开源，您可前往Git仓库获取最新版本SDK：github开源仓库。

添加依赖方式1：maven 依赖 #

需要先在maven的settings中配置火山引擎仓库地址：

<repositories>
  <repository>
    <id>bytedance-volcengine</id>
    <name>bytedance Volcengine</name>
    <url>https://artifact.bytedance.com/repository/Volcengine/</url>
  </repository>
</repositories>

然后就可以正常配置依赖了：

<dependency>

  <groupId>com.datarangers</groupId>

  <artifactId>datarangers-sdk-core</artifactId>
  
//建议使用最新版本，配置示例：1.5.13-release。 （注意-release也是版本的一部分）
  <version>{version}</version>

</dependency>

我们提供了一个封装完成的的starter包，您可以在pom中通过如下方式引入：

<dependency>

   <groupId>com.datarangers</groupId>

   <artifactId>datarangers-sdk-starter</artifactId>

   //建议使用最新版本，配置示例：1.5.13-release。 （注意-release也是版本的一部分）
   <version>{version}</version>

</dependency>

添加依赖方式2：离线依赖 #

如果您无法访问火山的maven仓库，或者没有jar包管理工具，可以从 github 下载离线包，或者自行build离线包: mvn package -DskipTests ，相关的jar所在路径为：

• datarangers-sdk-core/target/datarangers-sdk-core-{version}-release-jar-with-dependencies.jar
• datarangers-sdk-starter/target/datarangers-sdk-starter-{version}-release-jar-with-dependencies.jar

step2：初始化 SDK #

Java的开发框架通常由SpringBoot框架（推荐）、Spring容器化、普通Java程序，三种方式的代码结构有差异，但是初始化的配置参数一致，示例介绍如下。

HTTP #

• HTTP模式部署简单、可靠性高，还支持批量上报，因此推荐除同一个网络场景下推荐使用KAFKA模式上报外，其他场景推荐使用 HTTP 的方式。
• 使用HTTP模式时，sdk版本需要 >= 1.5.7。
• 使用HTTP模式时，初始化SDK时，通过datarangers.sdk.mode参数来指定当前使用哪种模式上报数据，datarangers.sdk.mode=http表示使用HTTP模式。

以下为您介绍不同环境下使用HTTP模式的示例和配置参数说明。

SAAS-云原生

# 设置环境信息
datarangers.sdk.env=saas_native
# 配置上报模式
datarangers.sdk.mode=http

# [domain]
# 服务器ip或域名
datarangers.sdk.domain=https://gator.****.com

# [app key]
datarangers.sdk.appKeys.20000000=xxxxxxxx

<!-- sdkMode config -->
<bean name="sdkMode" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
    <property name="staticField" value="com.datarangers.config.SdkMode.HTTP" />    
</bean>

<bean name="dataRangersSDKConfigProperties" class="com.datarangers.config.DataRangersSDKConfigProperties">
    <property name="env" ref="saas_native"/>
    <property name="domain" value="{domain}"/>
    <property name="mode" ref="sdkMode"/>
    <property name="appKeys">
      <map>
        <entry key=" ${appId}" value=" ${appKey}"/>
      </map>
    </property>
</bean>

DataRangersSDKConfigProperties properties = new DataRangersSDKConfigProperties();
// 设置模式
properties.setEnv(Constants.ENV_SAAS_NATIVE);
properties.setMode(SdkMode.HTTP);

// 设置domain和appKey
properties.setDomain("https://gator.***.com");

// 可以设置多个app，这里注意替换成真实的参数
properties.getAppKeys().put(Integer.valueOf(System.getenv("SDK_APP_1")), System.getenv("SDK_APP_KEY_1"));

// 设置服务端埋点实时校验url
// properties.getVerify().setUrl(System.getenv("VERIFY_URL"));

// 初始化collector
appEventCollector = new AppEventCollector("app", properties);
webEventCollector = new AppEventCollector("web", properties);

核心配置参数说明如下，更多全量配置参数请参见参考：Java SDK 全量配置项说明。

SaaS-非云原生

# SaaS-非云原生版 配置example
datarangers.sdk.env=saas
datarangers.sdk.mode=http

# [domain]
# 服务器ip或域名
# SaaS-非云原生版版本国内站
datarangers.sdk.domain=https://mcs.****.com
# SaaS-非云原生版版本国际站
#datarangers.sdk.domain=https://mcs.****.com

# [app key]
datarangers.sdk.appKeys. ${SDK_APP_1}= ${SDK_APP_KEY_1}

# [openapi]
# openapi的domain
# SaaS-非云原生版版国内站
datarangers.sdk.openapiConfig.domain=https://analytics.volcengineapi.com
# SaaS-非云原生版版国际站
#datarangers.sdk.openapiConfig.domain=https://analytics.byteplusapi.com

# openapi的ak, sk
datarangers.sdk.openapiConfig.ak= ${OPENAPI_AK}
datarangers.sdk.openapiConfig.sk= ${OPENAPI_SK}

<bean name="sdkMode" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
    <property name="staticField" value="com.datarangers.config.SdkMode.HTTP" />    
</bean>

<bean name="openapiConfig" class="com.datarangers.config.OpenapiConfig">
    <property name="domain" value=" ${openapi_domain}" />
    <property name="ak" value=" ${openapi_ak}" />  
    <property name="sk" value=" ${openapi_sk}" /> 
</bean>

<bean name="dataRangersSDKConfigProperties" class="com.datarangers.config.DataRangersSDKConfigProperties">
    <property name="env" ref="saas"/>
    <property name="domain" value="{domain}"/>
    <property name="mode" ref="sdkMode"/>
    <property name="appKeys">
      <map>
        <entry key=" ${appId}" value=" ${appKey}"/>
      </map>
    </property>
    <property name="openapiConfig" ref="openapiConfig"/>
</bean>

DataRangersSDKConfigProperties properties = new DataRangersSDKConfigProperties();
// 设置模式
properties.setEnv(Constants.ENV_SAAS);
properties.setMode(SdkMode.HTTP);

// 设置domain和appKey
properties.setDomain("https://mcs.****.com");

// 可以设置多个app，这里注意替换成真实的参数
properties.getAppKeys().put(Integer.valueOf(System.getenv("SDK_APP_1")), System.getenv("SDK_APP_KEY_1"));

// 设置openapi domain, AK,SK，这里注意替换成真实的参数
properties.getOpenapiConfig().setDomain("https://analytics.volcengineapi.com");
properties.getOpenapiConfig().setAk(System.getenv("OPENAPI_AK"));
properties.getOpenapiConfig().setSk(System.getenv("OPENAPI_SK"));

// 设置服务端埋点实时校验url
// properties.getVerify().setUrl(System.getenv("VERIFY_URL"));


// 初始化collector
appEventCollector = new AppEventCollector("app", properties);
webEventCollector = new AppEventCollector("web", properties);
mpEventCollector = new AppEventCollector("mp", properties);

核心配置参数说明如下，更多全量配置参数请参见参考：Java SDK 全量配置项说明。

私有化

# 私有化配置example
# 使用 http 上报模式
datarangers.sdk.mode=http
# sdk 上报地址，以http:// 或者 https:// 开头
datarangers.sdk.domain= ${SDK_DOMAIN}

#异步线程数量，当并发不够的时候可以调整该数据
#datarangers.sdk.threadCount=20

#[http config]
# 单位是毫秒
#datarangers.sdk.httpConfig.requestTimeout=10000
#datarangers.sdk.httpConfig.connectTimeout=10000
#datarangers.sdk.httpConfig.socketTimeout=20000

# 单位是s
#datarangers.sdk.httpConfig.keepAliveTimeout=30

# [batch]
# 使用 batch 的方式
# datarangers.sdk.sendBatch=false
# 批量的数量
#datarangers.sdk.batchSize=20
#datarangers.sdk.waitTimeMs=100

<bean name="sdkMode" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
    <property name="staticField" value="com.datarangers.config.SdkMode.HTTP" />    
</bean>

<bean name="dataRangersSDKConfigProperties" class="com.datarangers.config.DataRangersSDKConfigProperties">
    <property name="domain" value="{domain}"/>
    <property name="mode" ref="sdkMode"/>
</bean>

DataRangersSDKConfigProperties properties = new DataRangersSDKConfigProperties();
// 设置模式
properties.setMode(SdkMode.HTTP);

// 设置sdk domain，这里注意替换成真实的参数
properties.setDomain(System.getenv("SDK_DOMAIN"));

// 初始化collector
appEventCollector = new AppEventCollector("app", properties);
webEventCollector = new AppEventCollector("web", properties);
mpEventCollector = new AppEventCollector("mp", properties);

核心配置参数说明如下，更多全量配置参数请参见参考：Java SDK 全量配置项说明。

KAFKA模式（仅私有化） #

• KAFKA模式模式部署简单、可靠性高、上报数据的性能好，因此私有化场景下，集成SDK的服务和DataFinder在同一个网络时，建议使用该模式。
• 该模式只在私有化支持。
• 初始化SDK时，通过datarangers.sdk.mode参数来指定当前使用哪种模式上报数据，atarangers.sdk.mode=kafka表示使用KAFKA模式。

# 私有化配置example
# 使用kafka上报的模式
datarangers.sdk.mode=kafka
datarangers.sdk.kafka.bootstrapServers={ip1}:9192,{ip2}:9192

# kafka producer的 properties可以在这里进行配置
#datarangers.sdk.kafka.properties.retries=3

<bean name="sdkMode" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
    <property name="staticField" value="com.datarangers.config.SdkMode.KAFKA" />    
</bean>

<bean name="kafakConfig" class="com.datarangers.config.KafkaConfig">
    <property name="bootstrapServers" value=" ${ip:port}" />
    <property name="properties">
      <map>
        <entry key=" ${key}" value=" ${value}"/>
      </map>
    </property>
</bean>

<bean name="dataRangersSDKConfigProperties" class="com.datarangers.config.DataRangersSDKConfigProperties">
    <property name="mode" ref="sdkMode"/>
</bean>

DataRangersSDKConfigProperties properties = new DataRangersSDKConfigProperties();

// 设置模式
properties.setMode(SdkMode.KAFKA);

// 设置kafka
KafkaConfig kafkaConfig = new KafkaConfig();
properties.setKafka(kafkaConfig);

// 设置 BootstrapServers, etc: 127.0.0.1:9192,localhost:9192，这里注意替换成真实的参数
String bootstrapServers = System.getenv("SDK_KAFKA_BOOTSTRAP_SERVERS");
if(bootstrapServers == null){
    throw new IllegalArgumentException("bootstrapServers can not be empty");
}
kafkaConfig.setBootstrapServers(bootstrapServers);

// 如果需要设置其他属性，可以进行设置
// Map<String, Object> kafkaProperties = new HashMap<>();
// kafkaConfig.setProperties(kafkaProperties);

// 初始化collector
webEventCollector = new AppEventCollector("web", properties);
mpEventCollector = new AppEventCollector("mp", properties);
appEventCollector = new AppEventCollector("app", properties);

核心配置参数说明如下，更多全量配置参数请参见参考：Java SDK 全量配置项说明。

验证集成配置 #

查看启动日志 #

启动会打印如下日志，可以通过监测启动日志来确定配置是否符合预期。主要关注下env、sdkMode、domain等配置。

sdk config properties: 
enable: true 
env: PRIVATIZATION 
sync: false 
sdkMode: HTTP  
domain: ...
headers: {...}  
threadCount: 20 
queueSize: 10240 
sendBatch: false 
batchSize: 20 
waitTimeMs: 100 
httpConfig: {...} 
eventSavePath: logs/ 
eventSaveName: datarangers.log 
eventFilePaths: [logs/] 
eventSaveMaxFileSize: 100 
eventSaveMaxDays: -1 
openapiConfig: {...} 
kafka: null

HTTP 模式 Debug 验证 #

• 查看配置或自动日志，确定配置的 sdkMode为 HTTP，同时检查：
  • 检查datarangers.log文件是否存在数据，有埋点数据就属于异常（因为HTTP模式下，该文件不会有数据），请检查设置的sdkMode生效值。
  • 检查error-datarangers.log文件,如果存在数据，请检查错误信息
• Debug验证请求/响应报文
  如果通过日志无法确定是什么异常，可以用debug来看下详细的报错信息，Debug断点HttpUtils类167行(不同版本可能行数有所差异，但逻辑都是获取请求和响应报文)，以下截图为1.5.3版本。
  
  • resustStr为响应报文，其中如果e不为0，说明上报失败了，反之表示成功上报。
  • body为请求报文，如果响应报文了解到报错,可以获取下来看看数据格式是否正确。

HTTP 模式 curl 验证 #

可以使用 curl 命令，查看是否能正常上报。以下为各个环境的验证示例。

SaaS-云原生环境

appkey 需要替换成相应的配置。

curl --location --request POST 'https://gator.volces.com/sdk/log' \
--header 'User-Agent: DataRangers Java SDK' \
--header 'X-MCS-AppKey:  \${AppKey}' \
--header 'Content-Type: application/json' \
--data '{
    "app_type": "app",
    "_format_name": "datarangers_svc_app_log_v3_server_sdk_1.2.7",
    "header": {
        "custom": {
            "client": "fdaf",
            "__sdk_platform": "datarangers_sdk"
        },
        "device_id": 0,
        "timezone": 8,
        "tz_offset": 28800,
        "tz_name": "Asia/Shanghai",
        "user_unique_id": "test_sdk_user"
    },
    "user_unique_id": "xxxx",
    "event_v3": [
        {
            "event": "补贴查询",
            "params": {
                "cardNum": "cardNum",
                "year": "2021"
            },
            "local_time_ms": 1637734994778,
            "datetime": "2021-12-15 14:23:14"
        }
    ]
}'

如下返回表示上报成功：

{
    "e":0,
    "magic_tag":"server_sdk_log",
    "message":"success",
    "server_time":1664352669
}

SaaS-非云原生 环境

appkey 需要替换成相应的配置。

curl --location --request POST 'https://mcs.ctobsnssdk.com/v2/event/json' \
--header 'X-MCS-AppKey: ${AppKey}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user": {
        "user_unique_id": "test_sdk_user"
    },
    "header": {
        "custom": {
            "__sdk_platform": "datarangers_sdk_1.4.9-release"
        },
        "device_id": 0,
        "timezone": 8,
        "tz_offset": 28800,
        "tz_name": "Asia/Shanghai",
        "user_unique_id": "10.1.6.229"
    },
    "events": [
        {
            "event": "enterprise_search",
            "params": "{\"date_time\":\"20220803 15:19:56\",\"operateType\":9,\"moduleName\":\"\",\"productType\":0}",
            "local_time_ms": 1659511196363,
            "datetime": "2022-08-03 15:19:56"
        }
    ]
}'

如下返回表示成功：

{
    "e": 0,
    "message": "success",
    "sc": 1
}

私有化环境

domain 替换成相应的配置， app_id 也要修改成相应的配置。

curl --location --request POST '${domain}/sdk/log' \
--header 'User-Agent: DataRangers Java SDK' \
--header 'Content-Type: application/json' \
--data '{
    "app_type": "app",
    "_format_name": "datarangers_svc_app_log_v3_server_sdk_1.2.7",
    "app_id": 10000000,
    "header": {
        "custom": {
            "client": "fdaf",
            "__sdk_platform": "datarangers_sdk"
        },
        "device_id": 0,
        "timezone": 8,
        "tz_offset": 28800,
        "tz_name": "Asia/Shanghai",
        "user_unique_id": "test_sdk_user",
        "app_id": 10000000
    },
    "user_unique_id": "xxxx",
    "event_v3": [
        {
            "event": "补贴查询",
            "params": {
                "cardNum": "cardNum",
                "year": "2021"
            },
            "local_time_ms": 1637734994778,
            "datetime": "2021-12-15 14:23:14"
        }
    ]
}'

如下返回表示上报成功：

{
    "e":0,
    "magic_tag":"server_sdk_log",
    "message":"success",
    "server_time":1664352669
}

KAFKA 模式 (只支持私有化) #

查看kafka topic: sdk_origin_event 是否有数据上来，kafka 的使用方式参考文档：Kafka订阅(私有化) 增长分析-火山引擎。

注意事项 #

当前SaaS云原生/私有化和SaaS-非云原生场景下，在用户属性、Item属性等上报场景下的上报方式不完全一致，您需根据实际使用的环境情况，先了解下对应环境的数据上报注意事项。

发送普通事件 #

调用Java SDK的sendEvent API 即可上报事件，示例如下。

@Resource(name = "appEventCollector")
private EventCollector appEventCollector;

appEventCollector.sendEvent("uuid2", 10000000, null, "test_event_java_sdk", new HashMap<String, Object>() {{
    put("date_time", LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMdd")));
    put("current_time", LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMdd HH:mm:ss")));
}});

• 以上为一个上报示例，sendEvent API 有多个接口定义，可灵活的配置上报事件，详情请参见sendEvent 。
• 如果您希望批量上报事件，可使用 sendEvents API，详情请参见sendEvents。

设置用户属性 #

用户属性需要先在系统中创建之后再上报，上报时您可调用Java SDK的用户属性设置相关API设置用户属性，示例如下。

eventCollector.profileSet("uuid-1", 10000028, new HashMap<String, Object>() {{
    put("profile_1", "param_1");
    put("profile_2", "param_2");
    put("profile_3", "param_3");
    put("profile_4", "param_4");
}});

• 更多用户属性设置的API详情请参见用户属性相关接口。

设置Item属性 #

Item属性需要先在系统中创建之后再上报。业务对象内置的id属性，对应的字段名称为item_id，因此不需要再定义一个 id 属性。

以下为设置Item属性的示例。

List<Item> items = new ArrayList<>();
items.add(new BookItem("1000", "book").setName("Java").setPrice(100).setPublishDate(LocalDate.now()).setAuthors(author).setCategory("computer"));
items.add(new BookItem("1002", "book").setName("PHP").setPrice(100).setPublishDate(LocalDate.now()).setAuthors(author).setCategory("computer"));
eventCollector.itemSet(10000028, "book", items);

• 更多Item属性设置的API详情请参见业务对象相关接口。

发送携带item的事件 #

List<Item> items = new ArrayList<>();
items.add(new BookItem("1000", "book"));
items.add(new BookItem("1002", "book"));
items.add(new PhoneItem("1002", "phone"));
eventCollector.sendEvent("user-001", 10000028, null, "set_items", new HashMap<String, Object>() {{
    put("param1", "params");
    put("param2", items.get(0));
    put("param3", items.get(1));
    put("param4", items.get(2));
}});

上报匿名用户事件 #

如果需要使用服务端的方式上报匿名用户事件信息，需要把 user_unique_id 的值置为 ""(空字符串)，然后设置其他能关联上的设备信息，比如device_id、web_id、anonymousId。如果用户登录之后，能拿到user_unique_id，并且希望登录实名之后的行为能跟匿名之前的行为关联起来，那么在设置正确的user_unique_id之后，还需要带上匿名的时候设置的 device_id、web_id 或 anonymousId。

使用 device_id/web_id 上报匿名用户事件 #

当使用appEventCollector上报时，deviceId即为device_id，当使用webEventCollector、mpEventCollector上报时，deviceId 即为web_id。

Map<String, Object> eventParams = new HashMap<>();
eventParams.put("date_time", new SimpleDateFormat("yyyyMMdd").format(new Date()));
eventParams.put("event_param1", "value1");

// app/web/mp 这里都是deviceId 即可
Long deviceId = 10000L;
Header header = new HeaderV3.Builder()
        .setAppId(appId)
        .setDeviceId(deviceId)
        .setUserUniqueId("")
        .build();

// app/web/mp 使用不同的 EventCollector
// app
appEventCollector.sendEvent(header,"test_app_event_anonymous", eventParams, System.currentTimeMillis());

// 实名之后，关联匿名的行为, u1 会关联上之前设置的匿名用户行为(根据 deviceId 进行关联)
Header header2 = new HeaderV3.Builder()
        .setAppId(appId)
        .setDeviceId(deviceId)
        .setUserUniqueId("u1")
        .build();
appEventCollector.sendEvent(header2,"test_app_event_anonymous", eventParams, System.currentTimeMillis());

// web
webEventCollector.sendEvent(header,"test_web_event_anonymous", eventParams, System.currentTimeMillis());

// mp
mpEventCollector.sendEvent(header,"test_mp_event_anonymous", eventParams, System.currentTimeMillis());

使用 anonymousId 上报匿名用户事件 #

用户 device_id/web_id 都是long型，如果用户的自定义匿名ID是string的话，device_id/web_id无法满足，可以使用 anonymousId 这个string类型的字段来进行上报。
anonymousId 只支持web/mp，即要使用webEventCollector或者mpEventCollector来进行上报。

Map<String, Object> eventParams = new HashMap<>();
eventParams.put("date_time", new SimpleDateFormat("yyyyMMdd").format(new Date()));
eventParams.put("event_param1", "value1");

String anonymousId="test_anonymousId1";
Header header = new HeaderV3.Builder()
        .setAppId(appId)
        .setAnonymousId(anonymousId)
        .setUserUniqueId("")
        .build();
// web
webEventCollector.sendEvent(header,"test_web_event_anonymous", eventParams, System.currentTimeMillis());

// 实名之后，关联匿名的行为, u1 会关联上之前设置的匿名用户行为（根据 anonymousId 进行关联）
Header header2 = new HeaderV3.Builder()
        .setAppId(appId)
        .setAnonymousId(anonymousId)
        .setUserUniqueId("u1")
        .build();
webEventCollector.sendEvent(header2,"test_web_event_anonymous", eventParams, System.currentTimeMillis());

// mp
mpEventCollector.sendEvent(header,"test_mp_event_anonymous", eventParams, System.currentTimeMillis());

上报历史数据 #

注意：【SaaS-非云原生版本】历史数据导入需要隔天才能查看，【SaaS-云原生】、【私有化】版本可实时查看
如果数据的客户端时间超过七天，正常情况下无法导入，如需导入历史数据，需在header的custom字段中增加历史数据的标识__is_history，属性值设置为字符串"true"。
代码样例如下：

appEventCollector.sendEvent(userUniqueId, appId, new HashMap<String, Object>() {{
                    put("__is_history","true");
                }}, "test_event",
                new HashMap<String, Object>() {{
                    put("date_time", new SimpleDateFormat("yyyyMMdd").format(new Date()));
                    put("current_time",
                            new SimpleDateFormat("yyyyMMdd HH:mm:ss").format(new Date()));
                }},
                1637734994778);

先验证元数据，然后再在行为细查中去查看。

验证事件 #

事件发送成功之后，如果是第一次在新事件上报，最长可能需要等5分钟才能查看到。先检查元数据是否正常：

• 在“数据管理”>“元数据管理”> “一般事件”下查看是否有上报的事件。
• 在“数据管理”> “元数据管理”>“事件属性”下查看是否有上报的属性，以及属性的类型、属性关联的事件是否正确。

当事件在元数据中存在后，那么就可以直接在用户细查里面去查询。

验证用户属性 #

（1）先在“数据管理”>“元数据管理”>“用户属性”中验证用户属性是否存在，并检查属性类型是否符合预期。
（2）然后在“分析工具”>“用户分析”>“用户细查”中，点击并进入其中一个用户详情页面，查看最近上报的用户属性。

• 用户属性上报后，您可以在用户细查的最近个体画像中查看对应的用户属性。
  
• 用户属性相关的事件也同步上报后，您可在右下方的公共属性列表中查看到对应的用户属性。
  但是注意上报用户属性之后，一定要上报一条事件，否则用户细查这边的公共属性列表可能查询不到，因为用户细查是跟事件进行关联的。
  

验证业务对象 #

先在“数据管理”>“业务对象”下查看业务对象是否绑定到了事件。然后可以在行为细查进行查询，在行为细查里面会显示item_id。

如果想查看业务对象的属性值，可以在“分析工具” > “高级分析”> “业务对象分析”里面去查看。

埋点实时检测 #

在“数据管理” > “一般事件” > “验证埋点”上选择“服务端埋点”，然后输入需要检测的 user_unique_id，然后将url参数设置到 verify.url上即可。

当有该用户的埋点数据上报时，会看到上报的内容数据。

1. 注意该url有效期只有60分钟。
2. SDK版本 >= 1.5.7。
3. 如果url错误或者过期，实时检测不会上报或者上报失败，但是不影响正常的埋点上报。
4. 如果页面上查看不了内容数据，可以先查看实时埋点上报的日志：
   1. 搜索关键词 ERROR 日志 以及 “verify request” 和 “verify config”。
   2. 实时上报的相关的类为com.datarangers.sender.VerifySender，可以debug下。
   3. 没有错误日志，但是实时上报不显示内容，可以刷新下页面重新生成url。

注意事项 #

如果页面上查询不到数据，可以尝试下刷新页面。

• 使用自定义的 local_time_ms
• 高性能场景
• 查看上报时延
• 如何处理发送失败的数据
• 上报性能调试

AppEventCollector 使用的参数有两个：appType 和 properties。

• appType 只支持：
  • app，在服务端上传应用移动端相关的数据
  • web，在服务端上传应用web端相关的数据
  • mp，在服务端上传应用小程序端相关的数据
• properties 前缀都是datarangers.sdk。

更多Java SDK的常见问题请参见参考：Java SDK 集成 FAQ。