高级功能（iOS）

事件属性插件

事件属性插件是神策 iOS SDK 在 v4.4.6 及以后版本提供用于新增或修改埋点事件属性的高级功能，可通过属性插件筛选出特定事件，并实现对特定事件新增属性或修改某些属性。

接口介绍

SDK 提供了 - registerPropertyPlugin: 接口，可在初始化配置 SAConfigOptions 或者 SDK 实例 SensorsAnalyticsSDK 中注册自定义属性插件，注册继承 SAPropertyPlugin 基类的属性插件后，可以给指定的事件添加属性。

SAPropertyPlugin 基类接口介绍：

方法名

描述

- properties

用于获取插件采集的属性内容，这里可以返回自定义的属性的 NSDictionary。

- isMatchedWithFilter:

用于指定插件中属性的作用范围，默认值对 track 类型事件生效。其中实现 SAPropertyPluginEventFilter 协议的 filter 参数包含了可用于筛选的信息

SAPropertyPluginEventFilter 协议的接口说明：

方法名	描述
event	获取事件名，可根据事件名进行筛选
type	获取事件类型，SAEventType 的枚举值，可以通过位运算进行筛选： SAEventTypeTrack：对应 track 类型事件 SAEventTypeSignup：对应 track_signup 类型事件 SAEventTypeBind：对应 track_id_bind 类型事件 SAEventTypeUnbind：对应 track_id_unbind 类型事件 SAEventTypeProfileSet：对应 profile_set 类型事件 SAEventTypeProfileSetOnce：对应 profile_set_once 类型事件 SAEventTypeProfileUnset：对应 profile_unset 类型事件 SAEventTypeProfileDelete：对应 profile_delete 类型事件 SAEventTypeProfileAppend：对应 profile_append 类型事件 SAEventTypeIncrement：对应 profile_increment 类型事件 SAEventTypeItemSet：对应 item_set 类型事件 SAEventTypeItemDelete：对应 item_delete 类型事件 SAEventTypeDefault：默认事件类型，等于 SAEventTypeTrack & SAEventTypeSignup & SAEventTypeBind & SAEventTypeUnbind SAEventTypeAll：所有类型事件
time	事件触发的时间
hybridH5	是否为 H5 采集的事件

- priority

属性插件优先级，默认为 Default（500），高优先级的属性插件采集的同名属性会覆盖低优先级的属性

使用示例

可以根据事件名、事件类型、事件时间等条件筛选某些事件后，在这些事件中添加属性。先实现自己的属性插件，使用 - registerPropertyPlugin: 接口来注册属性插件，建议在初始化配置 SAConfigOptions 中注册。

参考示例代码如下 :

Objective-C

//  MyPropertyPlugin.h
@interface MyPropertyPlugin : SAPropertyPlugin

@end


//  MyPropertyPlugin.m
@implementation MyPropertyPlugin

- (BOOL)isMatchedWithFilter:(id)filter {
    return filter.type & SAEventTypeDefault;
}

- (SAPropertyPluginPriority)priority {
    return SAPropertyPluginPriorityDefault;
}

- (NSDictionary *)properties {
    return @{@"AppName": @"<#YOUR APP NAME#>"};
}

@end

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

	SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
    
	// 注册自定义属性插件
    MyPropertyPlugin *propertyPlugin = [[MyPropertyPlugin alloc] init];
    [options registerPropertyPlugin:propertyPlugin];

	// 初始化 SDK
	[SensorsAnalyticsSDK startWithConfigOptions:options];

    return YES;
}

Swift

//  MyPropertyPlugin.swift
class MyPropertyPlugin: SAPropertyPlugin {
    override func isMatched(with filter: SAPropertyPluginEventFilter) -> Bool {
        return filter.type.contains(SAEventType.default)
    }

    override func priority() -> SAPropertyPluginPriority {
        return SAPropertyPluginPriority.default
    }

    override func properties() -> [String : Any] {
        return ["AppName": "YOUR APP NAME"]
    }
}  

// AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { 
	
	let options = SAConfigOptions(serverURL: <#数据接收地址#>, launchOptions: launchOptions)

	//  注册事件属性插件
	SensorsAnalyticsSDK.start(configOptions: options)
        
	return true
}

//  MyPropertyPlugin.h
@interface MyPropertyPlugin : SAPropertyPlugin

@end


//  MyPropertyPlugin.m
@implementation MyPropertyPlugin

- (BOOL)isMatchedWithFilter:(id)filter {
    return filter.type & SAEventTypeDefault;
}

- (SAPropertyPluginPriority)priority {
    return SAPropertyPluginPriorityDefault;
}

- (NSDictionary *)properties {
    return @{@"AppName": @"<#YOUR APP NAME#>"};
}

@end

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

	SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
    
	// 注册自定义属性插件
    MyPropertyPlugin *propertyPlugin = [[MyPropertyPlugin alloc] init];
    [options registerPropertyPlugin:propertyPlugin];

	// 初始化 SDK
	[SensorsAnalyticsSDK startWithConfigOptions:options];

    return YES;
}

//  MyPropertyPlugin.swift
class MyPropertyPlugin: SAPropertyPlugin {
    override func isMatched(with filter: SAPropertyPluginEventFilter) -> Bool {
        return filter.type.contains(SAEventType.default)
    }

    override func priority() -> SAPropertyPluginPriority {
        return SAPropertyPluginPriority.default
    }

    override func properties() -> [String : Any] {
        return ["AppName": "YOUR APP NAME"]
    }
}  

// AppDelegate.swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { 
	
	let options = SAConfigOptions(serverURL: <#数据接收地址#>, launchOptions: launchOptions)

	//  注册事件属性插件
	SensorsAnalyticsSDK.start(configOptions: options)
        
	return true
}

拦截事件入库

1.11.16+ 版本 SDK 支持在事件入库前进行修改属性、删除事件，可以使用 - trackEventCallback: 中 block 参数进行设置：

block 中 eventName 参数为当前事件名。
block 中 properties 参数为当前事件属性，该参数为 NSMutableDictionary 类型，可直接修改此参数达到修改事件属性的目的。
block 返回值标志事件是否需要继续入库和上报： YES 事件会继续入库，NO 将删除此条事件。

警告

严禁在 block 中调用 - track: 、- trackInstallation:、 - login: 等触发事件的接口，会因循环调用而导致应用崩溃
block 返回 NO 时 SDK 将删除此条事件，所以请确保判断逻辑，以免造成误删除事件

Objective-C

[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName,
                                                               NSMutableDictionary *properties) {
    // BuyProduct 事件不进行入库
    if ([eventName isEqualToString:@"BuyProduct"]) {
        return NO;
    }
    
    // 删除 ViewProduct 事件 category 属性
    if ([eventName isEqualToString:@"ViewProduct"]) {
        [properties removeObjectForKey:@"category"];
    }
        
    return YES;
}];

Swift

SensorsAnalyticsSDK.sharedInstance()?.trackEventCallback({ (eventName, properties) -> Bool in
     // BuyProduct 事件不进行入库
     if (eventName == "BuyProduct"){
          return false
     }
     // 删除 ViewProduct 事件 category 属性
     if (eventName == "ViewProduct"){
          properties.removeObject(forKey: "category")
     }
     return true
})

[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName,
                                                               NSMutableDictionary *properties) {
    // BuyProduct 事件不进行入库
    if ([eventName isEqualToString:@"BuyProduct"]) {
        return NO;
    }
    
    // 删除 ViewProduct 事件 category 属性
    if ([eventName isEqualToString:@"ViewProduct"]) {
        [properties removeObjectForKey:@"category"];
    }
        
    return YES;
}];

SensorsAnalyticsSDK.sharedInstance()?.trackEventCallback({ (eventName, properties) -> Bool in
     // BuyProduct 事件不进行入库
     if (eventName == "BuyProduct"){
          return false
     }
     // 删除 ViewProduct 事件 category 属性
     if (eventName == "ViewProduct"){
          properties.removeObject(forKey: "category")
     }
     return true
})

自定义缓存加密

在基础 API 介绍文档中， SDK 缓存加密支持 AES 方式，如果需要使用其它加密方式，则需要注册自定义加密插件实现。

接口介绍

自定义加密插件实现协议，在 SDK 初始化时调用 - registerStorePlugin: 接口注册自定义加密插件即可开启。

SAStorePlugin 协议接口介绍：

方法名	描述
- type	重写该方法返回插件类型，插件类型不能重复
- upgradeWithOldPlugin:	重写这个方法，可以在插件注册的时候将一些老插件里的值使用新插件进行更新。这个方法可能会被调用多次，但是每次传入的插件都是不一样的。
- objectForKey:	根据指定 key 获取存储的数据，需要实现这个方法。如果数据已加密，需要进行解密
- setObject: forKey:	存储数据，实现这个方法，将数据进行存储。这里可以实现自定义加密
- removeObjectForKey:	删除指定 key，实现这个方法，将存储的对象进行删除

在自定义缓存加密存储插件时，需要由开发者来实现数据的存储与获取。

使用示例

目前 SDK 中内置了 SAAESStorePlugin 插件，该插件使用 AES 加密算法对本地存储数据进行加密。

Objective-C

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
[options registerStorePlugin:[[SAAESStorePlugin alloc] init]];
[SensorsAnalyticsSDK startWithConfigOptions:options];

Swift

let options = SAConfigOptions(serverURL: <#数据接收地址#>, launchOptions: launchOptions)
options.register(SAAESStorePlugin())
SensorsAnalyticsSDK.start(configOptions: options)

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
[options registerStorePlugin:[[SAAESStorePlugin alloc] init]];
[SensorsAnalyticsSDK startWithConfigOptions:options];

let options = SAConfigOptions(serverURL: <#数据接收地址#>, launchOptions: launchOptions)
options.register(SAAESStorePlugin())
SensorsAnalyticsSDK.start(configOptions: options)

限制 SDK 读取敏感属性

通过外部设置 SDK 的属性信息，限制 SDK 自动读取设备标识相关敏感信息，用于解决 SDK 读取敏感信息导致的合规问题。并且目前 SDK 中针对 IDFA、IDFV、运营商名称等信息都做了内存缓存，当获取成功时则使用缓存数据，不再重复调用。

设置该属性风险较高，使用前请咨询值班同学指导。

接口说明

- registerLimitKeys:

设置需要限制 SDK 自动获取的属性信息

通过设置限制属性的内容来代替 SDK 调用对应的接口来获取，用于避免 SDK 调用敏感 API

iOS SDK 预置 LimitKey 常量

SALimitKeyIDFA	IDFA，用于 $device_id 属性采集和匿名状态下的用户标识（distinct_id、AnonymousId），IDFA 被禁用时则使用 IDFV 作为用户标识，危险操作，请确保传值的正确性。
SALimitKeyIDFV	IDFV，用于 $device_id 属性采集和匿名状态下的用户标识（distinct_id、AnonymousId），IDFV 被禁用时则使用 UUID 作为用户标识，危险操作，请确保传值的正确性。
SALimitKeyCarrier	运营商，运营商名称，请确保传值的正确性。

使用示例

注意

IDFA 和 IDFV 涉及用户标识，请务必确保传入正确内容。

 SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions]; 

// 限制敏感 API
[options registerLimitKeys:@{SALimitKeyIDFA: @"自定义 IDFA", SALimitKeyIDFV: @"自定义 IDFV", SALimitKeyCarrier: @"自定义运营商"}];

// 开启 SDK
[SensorsAnalyticsSDK startWithConfigOptions:options]