# 概述

> 来源：https://help.gravity-engine.com/docs/getting-started/overview
> 概述 Gravity Engine 的数据接入流程、数据模型与数据格式，帮助业务、研发和测试团队明确接入顺序。





开始正式技术接入，您需要依次完成以下步骤：

1. 根据业务需求的整理，梳理出数据采集方案；
2. 由研发人员根据数据采集方案完成数据接入工作；
3. 验证数据接入正确性；
4. 数据接入验证无误之后，客户开始在媒体投放平台少量投放广告验证归因的正确性；
5. 归因验证无误之后，客户起量投放，并在引力引擎后台查看后向数据分析买量行为。

本篇文档将会对必要的接入相关知识做一个整体的介绍，本文的目标读者是所有与接入相关的同事，包括业务人员、研发人员、测试人员等。

## 1. 基础知识 [#1-基础知识]

### 1.1 数据模型 [#11-数据模型]

在进行数据接入之前，首先我们需要理解 引力引擎 中的数据是什么。

数据采集方案的设计实际上就是根据业务分析的目标确定采集哪些用户行为事件的过程。例如，如果要分析用户充值情况，要采集的可能是用户支付行为数据。用户行为数据可以分解为：谁 (`WHO`)，什么时候 (`WHEN`)，在哪里 (`WHERE`)，以什么方式 (`HOW`)，进行了充值行为 (`WHAT`)，如下图所示：

<img src="__img0" />

用户行为数据会被组织成**用户相关数据**和**行为事件相关数据**，并分别存入**用户表**和**事件表**中。

* 用户数据主要用于描述用户的状态和不会经常发生变化的属性；
* 事件数据用于描述与具体行为事件相关的信息。

在数据采集方案中，您需要确定在什么时机需要触发用户数据的上报，在什么时机需要触发行为事件的上报。

在我们的所有数据接入指南中，都会分别介绍上报行为事件数据和用户数据的方法。

关于数据模型的进一步了解，可以参考：[数据模型](/docs/getting-started/data-model)。

关于用户数据和事件数据的进一步了解，可以参考：[用户属性与事件属性](/docs/getting-started/event-and-user-properties)。

### 1.2 数据格式 [#12-数据格式]

无论通过哪一种方式接入数据，在发送到数据接收端的时候都使用统一的数据格式，和相同的数据限制。[数据规则](/docs/getting-started/data-rules)一章对数据格式和对应的数据限制做了详细的描述。

如果您通过 SDK 对接数据，只需要调用对应的接口，SDK 会将数据整理成需要的数据格式进行上报；如果您通过[API](/docs/server-integration)接入数据，则需要根据数据规则中的描述整理好数据格式，然后上报。

关于数据格式，需要特别注意命名规则和数据类型：

* 命名规则：事件名和属性名都只能包含字母、数字、和下划线 \_，以字母开头，不能超过 50 个字符，属性名对大小写不敏感；事件名对大小写敏感
* 属性值数据类型：

| 引力数据类型 | 取值样例                                               | 取值说明                      | 数据类型     |
| ------ | -------------------------------------------------- | ------------------------- | -------- |
| 文本     | "ABC"                                              | 字符的默认上限是 8KB              | String   |
| 整数     | 123                                                | 数据范围是-9E15 至 9E15         | Integer  |
| 浮点数    | 1.2                                                | 数据范围是-9E15 至 9E15         | Float    |
| 布尔值    | true,false                                         | -                         | Bool     |
| 时间     | "2023-01-01 00:00:00"                              | 上报格式 yyyy-MM-dd HH:mm:ss  | DateTime |
| 日期     | "2023-01-01"                                       | 上报格式 yyyy-mm-dd           | Date     |
| 列表     | \["Interstellar", "The Negro Motorist Green Book"] | 默认为字符串元素的数组，数组最大元素个数为 500 | Array    |

> **属性值的类型为在引力引擎后台创建该属性值时确定的类型，如果数据中某个属性的值的类型与此前确定的类型不符，此次事件将被系统丢弃!**

在 引力引擎 后台，您可能会注意到某些属性名是以 `$` 开头的，此类属性为预置属性。预置属性不需要特别设置，SDK 会在特定的事件发生时**默认采集**。

您需要特别注意的是，当数据格式或者数据类型没有正确设置的时候，数据无法入库。因此在接入阶段和接入之后，你可能需要通过 [元数据模块](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 来检验或者观察数据上报的正确性，并对出现的问题及时修正。

## 2. 接入必备信息 [#2-接入必备信息]

在正式由研发进行数据接入之前，需要再次确认以下信息已经准备好：

1. 项目 `Access Token`：在 引力引擎 后台创建项目的时候会生成项目的 `Access Token`，可以在 [应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面点击查看参数获取
2. 数据采集方案，要包括：
   * 数据接入的方式：客户端 SDK、API 或者混合使用的方式
   * 待接入数据的内容和触发的时机

恭喜您完成了接入前准备文档的阅读。接下来，您就可以根据选定的接入方式，参考对应的接入指南文档，开始进行数据接入了，不同技术栈接入指南导航请参考：[SDK总览](/docs/client-sdk/sdk-overview)

## 3. 验证接入是否成功 [#3-验证接入是否成功]

在正式上线之前，请参考对应SDK接入文档完成接入校验。