SDK 是如何存储事件数据的？

一、前言

为了最大限度地保证事件数据的准确性、完整性和及时性，数据采集 SDK 需要及时地将事件数据同步到服务端。但在某些情况下，比如手机处于断网环境，或者根据实际需求只能在 Wi-Fi 环境下才能同步数据等，可能会导致事件数据同步失败或者无法进行同步。因此，数据采集 SDK 需要先把事件数据缓存在本地，待符合一定的策略（条件）之后，再去同步数据[1]。

二、数据存储方式

在 iOS 应用程序中，从 “数据缓存在哪里” 这个维度看，缓存一般分为两种类型：

• 内存缓存
• 磁盘缓存

内存缓存是将数据缓存在内存中，供应用程序直接读取和使用。优点是读写速度极快。缺点是由于内存资源有限，应用程序在系统中申请的内存，会随着应用程序生命周期的结束而被释放。这就意味着，如果应用程序在运行的过程中被用户强杀或者出现崩溃的情况，都有可能导致内存中缓存的数据丢失。因此，将事件数据缓存在内存中不是最佳选择。

磁盘缓存是将数据缓存在磁盘空间中，其特点正好与内存缓存相反。磁盘缓存容量大，但是读写速度相对于内存缓存来说要慢一些。不过磁盘缓存是持久化存储，不受应用程序生命周期的影响。一般情况下，一旦数据成功保存在磁盘中，丢失的风险就非常低。因此，即使磁盘缓存数据读写速度较慢，但综合考虑下，磁盘缓存是缓存事件数据的最优选择。

由于磁盘缓存是一种可以持久化存储的方案，对于存储事件数据是一种最优的选择。在 iOS 中有多种持久化存储的方案，比如 KeyChain、NSUserDefaults、文件存储、数据库存储等都可以做持久化存储。那我们的事件数据使用哪种方案比较好呢？

我们知道 KeyChain、NSUserDefaults 是一种轻量级的存储方案，比如登录用户的用户名、登录状态等，使用 KeyChain 或者 NSUserDefaults 是一种不错的选择。但是对于大量的事件数据而言，这两种存储方案就无能为力了。

文件存储可以满足存储大量数据的需求，因此可以使用文件来存储采集的事件数据。其实，在 SDK 的一些前期版本，我们就是使用文件来存储事件数据的。文件存储相对来说还是比较简单的，主要操作就是写文件和读文件。我们每次都是将所有的数据写入同一个文件，写入的数据量越大，文件缓存性能越好。当然，文件存储还是不够灵活的，我们很难使用更细的粒度去操作数据，比如，很难对其中的某一条数据进行读和写的操作。

有没有其他的方式，可以满足对数据灵活操作的需求呢？答案是肯定的，数据库就满足这个需求。在 iOS 应用程序中，使用的数据库一般是 SQLite 数据库。SQLite 是一个轻量级的数据库，数据存储简单高效，使用也非常简单。相对于文件存储来说，数据库存储更加灵活，可以实现对单条数据的插入、查询和删除操作，同时调试也更容易[1]。

三、事件数据存储

3.1 存储策略

实现 SDK 中的数据库时，为了保证数据的完整性和准确性，采用了较为完善的存储策略：

1. 开发者在初始化 SDK 时，可以根据需要通过 - setMaxCacheSize: 方法设置本地缓存事件的最大条数。本地缓存事件的默认值是 10000 条。当开发者设置的最大缓存事件条数小于 10000 时，则使用默认值；
2. 执行数据采集任务时，采集的数据首先缓存到本地数据库。数据写入时，会判断数据库里缓存的事件条数是否超过设定的最大值；如果超过设定的最大缓存事件条数，则删除最先入库的 100 条数据，然后执行入库操作；
3. SDK 会定时检查是否满足上报策略，满足上报策略时，会把数据库里的数据打包上报到服务端，上报成功后会删除已上报的数据，上报失败则不删除。

3.2 数据库表的设计

SDK 采集的事件数据中，会有很多字段，比如事件名称、预置公共属性和用户自定义属性等。虽然事件数据中包含的属性比较多，但是存储数据无需关心具体的细节，可以将一个事件数据当做整体存储到数据表的一个字段中，从而提高数据的操作效率。

具体的结构如表 3-1 所示：

表 3-1 事件数据的存储结构

3.3 具体实现

SDK 采集数据过程中，会频繁的执行缓存数据、上报数据和删除数据等耗时操作。为了保证 SDK 的数据采集不影响用户的 App 性能，这些耗时的操作全部在子线程中完成。SDK 在执行数据存储和数据上报会涉及到 SAEventStore 、SAEventFlush、SAHTTPSession、SAEventTracker 等几个关键类：

• SAEventStore: 负责事件数据的存储操作；
• SAEventFlush: 负责数据的上报；
• SAHTTPSession: 负责将上报数据的任务添加到队列，等待执行；
• SAEventTracker: 负责 track 事件和检查是否达到上报条件。

3.3.1. 初始化工具类

1. 在初始化 SDK 时，会对 SAEventTracker 工具类进行初始化：

_eventTracker = [[SAEventTracker alloc] initWithQueue:_serialQueue]; 

1. 在 SAEventTracker 的初始化方法里对 SAEventStore 和 SAEventFlush 两个工具类进行初始化：

- (instancetype)initWithQueue:(dispatch_queue_t)queue {
    self = [super init];
    if (self) {
        _queue = queue;
 
        dispatch_async(self.queue, ^{
            self.eventStore = [[SAEventStore alloc] initWithFilePath:[SAFileStore filePath:@"message-v2"]];
            self.eventFlush = [[SAEventFlush alloc] init];
        });
    }
    return self;
}

1. 初始化 SAEventStore 时，传入的 filePath 参数是用于创建数据库的路径。SAEventStore 的初始化如下：

- (instancetype)initWithFilePath:(NSString *)filePath {
    self = [super init];
    if (self) {
        NSString *label = [NSString stringWithFormat:@"cn.sensorsdata.SAEventStore.%p", self];
        _serialQueue = dispatch_queue_create(label.UTF8String, DISPATCH_QUEUE_SERIAL);
        // 直接初始化，防止数据库文件，意外删除等问题
        _recordCaches = [NSMutableArray array];
 
        [self setupDatabase:filePath];
    }
    return self;
}

1. 在方法 - setupDatabase: 里对封装了数据库的工具类 SADatabase 初始化，在 SADatabase 创建了数据库文件和表：

- (instancetype)initWithFilePath:(NSString *)filePath {
    self = [super init];
    if (self) {
        _filePath = filePath;
        _serialQueue = dispatch_queue_create("cn.sensorsdata.SADatabaseSerialQueue", DISPATCH_QUEUE_SERIAL);
        [self createStmtCache];
        [self open];
        [self createTable];
    }
    return self;
} 

3.3.2. 数据入库

1. 对于校验成功的数据，会尝试把数据存入到数据库，如果数据库打开失败，会把数据先保存在内存中的一个数组中：

- (BOOL)insertRecord:(SAEventRecord *)record {
    BOOL success = [self.database insertRecord:record];
    if (!success) {
        [self.recordCaches addObject:record];
    }
    return success;
} 

1. 在监听到数据库创建成功时，会尝试把缓存在内存中的数据插入数据库，如果插入失败，会重试 3 次：

#pragma mark - observe
 
- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context {
    if (context != SAEventStoreContext) {
        return [super observeValueForKeyPath:keyPath ofObject:object change:change context:context];
    }
    if (![keyPath isEqualToString:SAEventStoreObserverKeyPath]) {
        return;
    }
    if (![change[NSKeyValueChangeNewKey] boolValue] || self.recordCaches.count == 0) {
        return;
    }
    // 对于内存中的数据，重试 3 次插入数据库中。
    for (NSInteger i = 0; i < 3; i++) {
        if ([self.database insertRecords:self.recordCaches]) {
            [self.recordCaches removeAllObjects];
            return;
        }
    }
} 

1. 插入事件数据是比较频繁的操作，如果每次都做 “预解析 SQL 语句” 的操作，将会造成资源的大量浪费。对于插入数据来说，每次操作的 SQL 语句都是相同的，因此 “预解析 SQL 语句” 只需执行一次即可。由于每次需要绑定不同的数据，我们只需要重置一下之前的 sqlite3_stmt，然后重新绑定新的数据即可[1]。插入数据的逻辑如下：

- (BOOL)insertRecord:(SAEventRecord *)record {
    if (![record isValid]) {
        SALogError(@"%@ input parameter is invalid for addObjectToDatabase", self);
        return NO;
    }
    if (![self databaseCheck]) {
        return NO;
    }
 
    if (![self preCheckForInsertRecords:1]) {
        return NO;
    }
 
    NSString *query = @"INSERT INTO dataCache(type, content) values(?, ?)";
    sqlite3_stmt *insertStatement = [self dbCacheStmt:query];
    int rc;
    if (insertStatement) {
        sqlite3_bind_text(insertStatement, 1, [record.type UTF8String], -1, SQLITE_TRANSIENT);
        sqlite3_bind_text(insertStatement, 2, [record.content UTF8String], -1, SQLITE_TRANSIENT);
        rc = sqlite3_step(insertStatement);
        if (rc != SQLITE_DONE) {
            SALogError(@"insert into dataCache table of sqlite fail, rc is %d", rc);
            return NO;
        }
        self.count++;
        SALogDebug(@"insert into dataCache table of sqlite success, current count is %lu", self.count);
        return YES;
    } else {
        SALogError(@"insert into dataCache table of sqlite error");
        return NO;
    }
} 

3.3.3. 数据删除

1. 在达到上报条件时，会触发数据上报。默认情况下是每 15 秒上报一次，或者缓存的数据达到 100 条时进行一次上报。在非 Debug 模式下，每次上报 50 条数据：

- (void)flushAllEventRecords {
    if (![self canFlush]) {
        return;
    }
    BOOL isFlushed = [self flushRecordsWithSize:self.isDebugMode ? 1 : 50];
    if (isFlushed) {
        SALogInfo(@"Events flushed!");
    }
} 

1. 对于已经上报成功的数据，SDK 会将其从数据库中移除，防止数据的重复上报：

......
// flush
__weak typeof(self) weakSelf = self;
[self.eventFlush flushEventRecords:encryptRecords completion:^(BOOL success) {
__strong typeof(weakSelf) strongSelf = weakSelf;
void(^block)(void) = ^ {
if (!success) {
[strongSelf.eventStore updateRecords:recordIDs status:SAEventRecordStatusNone];
return;
}
// 5. 删除数据
if ([strongSelf.eventStore deleteRecords:recordIDs]) {
[strongSelf flushRecordsWithSize:size];
}
};
if (sensorsdata_is_same_queue(strongSelf.queue)) {
block();
} else {
dispatch_sync(strongSelf.queue, block);
}
}];
...... 

3.4 数据流程

当 SDK 调用 track 相关方法时，首先是 SDK 会对事件数据的各项属性进行合法性校验，校验通过后将事件数据存储到数据库。在 SDK 初始化时启动的定时器会定时检查是否满足上报条件，当符合上报时，再将数据上报到服务端，最后再把上报成功的数据从数据库中删除。工作流程如图 3-1 所示：

图 3-1 数据采集流程

四、总结

本文介绍了神策 iOS SDK[2] 中使用到的存储方式和具体使用流程。希望通过这篇文章的介绍，大家能够对神策 iOS SDK 存储模块有一个较为全面的了解。

参考文献：

[1]王灼洲.iOS全埋点解决方案[M].北京:机械工业出版社,2020:162-197.

[2]https://github.com/sensorsdata/sa-sdk-ios