腾讯位置商业授权iOS 轨迹SDK

iOS 轨迹SDK

轨迹云是一套轨迹管理服务，可应用于车辆管理、外业人员管理、设备管理追踪、位置/行程分享等场景中，可帮助开发者快速实现业务需求。

iOS 轨迹SDK是一款封装轨迹云服务用于iOS端开发产品，支持轨迹上报、轨迹查询等服务。

SDK名称：腾讯地图轨迹SDK

开发者：深圳市腾讯计算机系统有限公司

版本：1.2.0

主要功能：轨迹上报、轨迹查询等

个人信息处理规则：https://privacy.qq.com/document/preview/a5b9d8dd2788457197dad50cc407234a

使用说明：https://lbs.qq.com/mobile/iosTrackSDK/iosTraceGuide/iosGeoUse

参考手册：https://mapapi.qq.com/sdk/track/ios/index.html

合规指南：https://lbs.qq.com/complianceGuides/guides/sdkGuides/traceSdkComplianceGuide

一、使用说明

轨迹SDK不支持服务创建，与轨迹云服务一样，需要在控制台-轨迹云-我的轨迹服务中创建。

二、配额限制

在接入轨迹SDK后，需要在官网控制台-配额管理-账户额度中找到 轨迹上传（轨迹SDK） 进行额度配置。

	个人开发者		企业开发者		商业授权开发者
接口	调用量上限（次/日）	并发量上限（次/秒）	调用量上限（次/日）	并发量上限（次/秒）	调用量上限（次/日）	并发量上限（次/秒）
轨迹上传（轨迹SDK）	10,000	5	10,000	5	500,000	50

一、获取KEY

1、登录腾讯位置服务官网，如果没有注册过账号，请注册新账号成为腾讯位置服务开发这。

2、进入[控制台](https://lbs.qq.com/dev/console/home)，选择应用管理-我的应用-创建应用-添加Key创建您的Key。

在添加面板中勾选地图SDK功能，下方输入框中输入授权包名。

二、手动配置

依赖项：

腾讯地图SDK
QMapFoundationKit >= 3.3.0
Protobuf 版本3.22.1
libz.1.2.5.tbd

1、将上述Framework以及资源Bundle加如Xcode工程中。

2、在工程->Targets->Build Phases->Link Binary With Libraries中添加如下系统库

三、自动部署

1、通过CocoaPods集成

在工程的Podfile 里面添加以下代码：

复制代码

pod 'Tencent-MapTrackSDK', '1.1.2'

然后在工程中引入腾讯定位SDK，如果已引入带有腾讯定位SDK的库，则不需要手动引入。

四、配置KEY

在工程的"AppDelegate.m"中引入 #import <TencentMapTrackKit/TencentMapTrackService.h>并配置开发者Key，此步骤为必须。

复制代码

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     // 轨迹SDK隐私合规接口
    [[TencentMapTrackService service] setPrivacyAgreement:YES];
    [[TencentMapTrackService service] setApiKey:@"AIPKey"];
    // ......
}

隐私合规接口

在调用相关服务前需要保证用户同意隐私政策后调用setPrivacyAgreement接口，设置同意轨迹SDK的隐私政策后才能正常使用轨迹SDK功能。

复制代码

[[TencentMapTrackService service] setPrivacyAgreement: YES];

轨迹上报

本章介绍轨迹上报的实现方式，以及相关的上报配置。

一、初始化信息

注意： secretKey 是必须填入的，轨迹上报的KEY要在控制台-应用管理-我的应用开启签名校验，将系统生成的SecretKey进行设置。

复制代码

// 请求key
[TencentMapTrackService service].apiKey = @"您的APIKey";
// 设备id
[TencentMapTrackService service].deviceID = @"deviceID";
// secrectKey，在官网控制台-应用管理-我的应用中给KEY开启签名校验，系统分配的 SecretKey
[TencentMapTrackService service].secretKey = @"webservice的secrectKey";

二、初始化采集配置

轨迹sdk不提供服务service_id 创建，需要在官网控制台-我的轨迹服务中进行创建。

复制代码

// 初始化采集配置
TencenMapTrackTracerConfig *config = [[TencenMapTrackTracerConfig alloc] init];
config.entityID = @"entityID"; // 终端id
config.entityName = @"entityName"; // 终端名称
config.serviceID = @"serviceID"; // 服务id
config.entity_desc = @"终端描述"; //终端描述
config.entityFields = @{@"name":@"张三",@"age":@18}; //终端自定义字段

注意：终端自定义字段要提前通过创建终端自定义字段服务进行创建。

三、创建轨迹采集实例

复制代码

// 声明轨迹采集实例
@property (nonatomic, strong) TencentMapTrackTracer *tracer;

self.tracer = [self.tracker createTracerWithConfig:config];
//设置代理
self.tracer.delegate = self;
// 设置缓存点数最⼤数量，3000个
self.tracer.maxCacheCount = 3000;
//设置上报间隔，5s
self.tracer.refluxInterval = 5;

四、配置定位源

复制代码

// 初始化默认定位源（基于腾讯定位SDK）
TencentMapTraceDefaultPointSource *source = [[TencentMapTraceDefaultPointSource alloc] initWithApiKey:@"xxx"];;

// 设置定位源
self.tracer.tracePointSource = source;
// 设置采集间隔
self.tracer.tracePointSource.traceInterval = 2;

// 申请定位权限
[self.tracer.tracePointSource requestWhenInUseAuthorization];
// 申请后台定位
[self.tracer.tracePointSource setAllowsBackgroundLocationUpdates:YES];

TencentMapTraceDefaultPointSource详见：参考手册

五、轨迹采集回调

复制代码

/**
 * @brief 采集到轨迹点写进缓存前回调
 * @param tracer 轨迹采集对象
 * @param point 采集到的轨迹点
 * @return 是否写⼊到缓存
 */
- (BOOL)tracer:(TencentMapTrackTracer *)tracer onTracePointBeforeCache:
(TencentMapTrackTracePoint *)point;


/**
 * @brief 轨迹采集状态反馈
 * @param tracer 轨迹采集对象
 * @param code 状态码
 * @param result 终端检验结果
 */
- (void)tracer:(TencentMapTrackTracer *)tracer onTraceFeebback:
(TencentMapTrackStatusCode)code entityVerified:
(TencenMapTrackTracerEntityResult * _Nullable)result;


/**
 * @brief 轨迹采集开始回调
 * @param tracer 轨迹采集对象
 */
 - (void)didStartTrace:(TencentMapTrackTracer *)tracer;

/**
 * @brief 轨迹采集停⽌回调
 * @param tracer 轨迹采集对象
 */
 - (void)didEndTrace:(TencentMapTrackTracer *)tracer;

/**
 * @brief 轨迹点上报回流
 * @param tracer 轨迹采集对象
 * @param info 回流信息
 */
- (void)tracer:(TencentMapTrackTracer *)tracer onTracePointRefluxed:
(TencentMapTrackTraceRefluxInfo *)info;


/**
 * @brief 轨迹点被淘汰回调
 * @param tracer 轨迹采集对象
 * @param info 轨迹点被淘汰信息
 */
- (void)tracer:(TencentMapTrackTracer *)tracer onTracePointEvicted:
(TencentMapTrackTracePointEvictedInfo *)info;

六、轨迹点自定义字段

轨迹点自定义字段需要提前通过轨迹自定义字段管理创建。

在轨迹采集监听的 onTracePointBeforeCache 回调中通过 TencentMapTrackTracePoint 设置轨迹点自定义字段。

复制代码

- (BOOL)tracer:(TencentMapTrackTracer *)tracer onTracePointBeforeCache:(TencentMapTrackTracePoint *)point
{
	NSDictionary *dict = @{@"id":@1,@"text":@"测试点"};
	point.extraParam = dict;
}

七、开始采集

复制代码

[self.tracer startTrace];

八、停止采集

复制代码

-(void)endTraceWithOption:(TencentMapTrackTracerEndTraceOption)option;

轨迹查询

本章介绍轨迹查询的实现方式。

一、初始化配置

复制代码

// 初始化轨迹查询配置项
TencentMapTrackQuerierBaseOption *opt = [[TencentMapTrackQuerierBaseOption alloc] init];

opt.service_id = @"service_id"; // 服务id
opt.entity_id = @"entity_id"; // 终端id
opt.start_time = 1691685446; // 开始时间戳
opt.end_time  = 1691739446; // 结束时间戳

// 额外请求字段
opt.extraQueryParams = @{@"test":@"tset"};

// 获取查询实例
self.querier = [self.tracker createQuerier];
// 设置代理
self.querier.delegate = self;
// 进⾏查询
NSURLSessionDataTask *task = [self.querier queryTrackWithOption:opt];

二、轨迹查询回调

复制代码

/**
 * @brief 轨迹查询回调
 */
@protocol TencentMapTrackQuerierDelegate <NSObject>

@optional
/**
 * @brief 查询轨迹回调
 * @param querier 轨迹查询对象
 * @param option 轨迹查询参数类
 * @param response 轨迹查询结果
 */
- (void)trackQuerier:(TencentMapTrackQuerier *)querier onTrackQuery:
(TencentMapTrackQuerierBaseOption *)option response:
(TencentMapTrackQuerierBaseResponse *)response;

/**
 * @brief 查询轨迹失败回调
 * @param querier 轨迹查询对象
 * @param option 轨迹查询参数类
 * @param error 轨迹查询错误
 */
- (void)trackQuerier:(TencentMapTrackQuerier *)querier onTrackQuery:
(TencentMapTrackQuerierBaseOption *)option failWithError:(NSError *)error;