1. 事件属性插件

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

1.1. 接口介绍

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),高优先级的属性插件采集的同名属性会覆盖低优先级的属性

1.2. 使用示例

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

参考示例代码如下 :

//  MyPropertyPlugin.h
@interface MyPropertyPlugin : SAPropertyPlugin

@end


//  MyPropertyPlugin.m
@implementation MyPropertyPlugin

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

- (SAPropertyPluginPriority)priority {
    return SAPropertyPluginPriorityDefault;
}

- (NSDictionary<NSString *,id> *)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;
}
CODE
//  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
}
CODE

2. 拦截事件入库

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

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

警告

  • 严禁在 block 中调用 - track:- trackInstallation: - login:  等触发事件的接口,会因循环调用而导致应用崩溃
  • block 返回 NO 时 SDK 将删除此条事件,所以请确保判断逻辑,以免造成误删除事件
[[SensorsAnalyticsSDK sharedInstance] trackEventCallback:^BOOL(NSString *eventName,
                                                               NSMutableDictionary<NSString *,id> *properties) {
    // BuyProduct 事件不进行入库
    if ([eventName isEqualToString:@"BuyProduct"]) {
        return NO;
    }
    
    // 删除 ViewProduct 事件 category 属性
    if ([eventName isEqualToString:@"ViewProduct"]) {
        [properties removeObjectForKey:@"category"];
    }
        
    return YES;
}];
CODE
SensorsAnalyticsSDK.sharedInstance()?.trackEventCallback({ (eventName, properties) -> Bool in
     // BuyProduct 事件不进行入库
     if (eventName == "BuyProduct"){
          return false
     }
     // 删除 ViewProduct 事件 category 属性
     if (eventName == "ViewProduct"){
          properties.removeObject(forKey: "category")
     }
     return true
})
CODE

3. 自定义缓存加密

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

3.1. 接口介绍

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

SAStorePlugin 协议接口介绍:

方法名描述

- type

重写该方法返回插件类型,插件类型不能重复

- upgradeWithOldPlugin:

重写这个方法,可以在插件注册的时候将一些老插件里的值使用新插件进行更新。这个方法可能会被调用多次,但是每次传入的插件都是不一样的。

- objectForKey:

根据指定 key 获取存储的数据,需要实现这个方法。如果数据已加密,需要进行解密

- setObject: forKey:

存储数据,实现这个方法,将数据进行存储。这里可以实现自定义加密

- removeObjectForKey:

删除指定 key,实现这个方法,将存储的对象进行删除

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

3.2. 使用示例

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

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
[options registerStorePlugin:[[SAAESStorePlugin alloc] init]];
[SensorsAnalyticsSDK startWithConfigOptions:options];
CODE
let options = SAConfigOptions(serverURL: <#数据接收地址#>, launchOptions: launchOptions)
options.register(SAAESStorePlugin())
SensorsAnalyticsSDK.start(configOptions: options)
CODE

4. 限制 SDK 读取敏感属性

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

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

4.1. 接口说明

- 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

运营商,运营商名称,请确保传值的正确性。


4.2. 使用示例

注意

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


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

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

// 开启 SDK
[SensorsAnalyticsSDK startWithConfigOptions:options]
CODE