- Ptengine Help Center
- 设置
- iOS采集SDK集成
iOS采集SDK集成
第一部分：基础SDK集成：
【说明】 完成第一部分基础SDK集成，就可以实现APP的用户统计，启动次数统计，使用时长统计，PV统计，APP崩溃的统计。如果您需要更多的自定义统计，请参考第二部分的“自定义代码集成”。
-
1. 导入SDK
您可以选择如下任意一种方式，将SDK导入App工程：
1.1 拖拽导入
直接拖拽下载下来的相关SDK(正式版为: PtTrackSDK.framework)到App工程中的Frameworks目录下，并选中”Copy item if needed”,点击Finish，以保证SDK拷贝到当前工程目录中，如图:
1.2 右键导入
选中App工程中的Frameworks文件夹或者工程文件，右键菜单选择”Add Files to ‘demo.project’””, 以保证SDK(正式版为: PtTrackSDK.framework)拷贝到当前工程目录中，如图：
-
2. 添加依赖框架
在App -> TARGETS -> Build Phases 配置项中通过+号加入图示中的依赖框架，并在Other Linker Flag配置项中添加-ObjC(此处务必添加，否则可导致SDK部分功能不可用)：
-
. 配置 AppKey 和 渠道
Appkey，即Ptengine for App中获取的AppID。
当app启动时，需要先通过SDK接口注册appKey，此方法必须调用：
-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[PtAgent sharedInstance] PTStartWithAppKey:@"**********" channel:**];
}
请确保该方法在application didFinishLaunchingWithOptions:的第一行处调用，已确保在程序启动时要加载的所有ViewController都被成功监听。
AppKey:为后台创建应用后生成的key值，不能为空, 此处可替换为相应的值。
channel:为app发布的渠道名称，如果传nil, 则使用默认值“AppStore”, 如果app要发布到其他渠道，请填写相关渠道名称。
第二部分：自定义代码集成
您可以通过调用如下接口，实现pageView、自定义事件和App错误信息的统计监测。
-
4. 自定义事件接口
4.1 部署自定义事件并添加属性接口
如果想要部署自定义事件，并给该事件设置自定义属性，可通过调用如下接口实现。
/**
* Use this method to track an event with user-defined value.
* @param eventName, this value can't be nil or empty
* @param properties, you can bind some event properties for this event, if you don't need it, just pass nil.
*
************************************************************************************************************************************
* [[PtAgent sharedInstance]PTTrackEvent:@"Buy" withProperties:@{@"price":@"200.00", @"title":@"xxx", ...}];
************************************************************************************************************************************
*
*/
- (void)PTTrackEvent:(NSString *)eventName withProperties:(nullable NSDictionary *)properties;
4.2 自定义事件开始时间接口，用于统计事件时长
开始记录时间接口与结束记录时间接口的事件名要保持一致，用于统计某一个事件的执行时间
/** * Mark the begin time for defined event. */ - (void)PTBeginEvent:(NSString *)eventName;
4.3自定义事件结束时间接口，用于统计事件时长
开始记录时间接口与结束记录时间接口的事件名要保持一致，用于统计某一个事件的执行时间。
结束记录时间接口也可传递其他的变量值作为自定义属性。
/** * Mark the end time for defined event, you can specify the event properties for yourself. * This method should be paired with PTBeginEvent, and eventName must be same. */ - (void)PTEndEvent:(NSString *)eventName withProperties:(nullable NSDictionary*)properties;
4.4 自定义用户登录事件接口
登录成功之后请把当前的登入用户作为值传入
/** * Track the user login info with specific properties. */ - (void)PTTrackUserLogin:(NSString *)userID withProperties(nullable NSDictionary*)properties;
-
5. 虚拟PV接口
如果某个特殊业务场景或者一个自定义UIView想作为一个PV统计，可调用该接口实现。对于UIViewController容器类，SDK会自动采集PV数据，所以不要使用该接口对UIViewController类进行重复的PV数据采集。
/** * If you want to track 'PV' data for user-defined UIView, you can invoke this API. But DON'T use it for UIViewController container, because our SDK has tracked 'PV' data automatically for UIViewController. */ - (void)PTTrackPVForCustomViewController:(NSString *) withProperties(nullable NSDictionary*)properties;
-
6. 自定义pageView name接口
基础SDK包已经默认采集了UIViewController 的PV数据，默认采集的页面名称为当前Controller类名，但如果您想要自定义当前ViewController的页面名称，可通过如下接口调用：
/** * Because the 'PV' data with default page name for UIViewController has been tracked automatically by PTTrackSDK, * so if you want to re-define the page name value, you can invoke this API as soon as [viewWillAppear:] is triggered. * The default value is current class name of UIViewController * @param redefinedName: new page name value. * @param properties: bind the page properties for PV data. * @param viewController: the instance of current UIViewController. */ - (void)PTRedefinePVName:(NSString*)redefinedName withProperties:(nullable NSDictionary*)properties forViewController:(id)viewContainer;
-
7. App错误信息统计接口
如果想要采集某些场景下的错误信息，比如app中请求http失败，或者登陆失败等等，请调用如下接口：
/** * Track the error info if you want to define in some scene. For example, http request is failed... * @param exceptionInfo error info * @param code error code */ - (void)PTTrackException:(nullable NSString *)exceptionInfo exceptionCode:(NSInteger)code;
-
8. App中包含HTML界面的事件统计方式
SDK提供了支持对HTML界面的事件统计javascript接口，使用这些接口之前需要先进行简单的注册配置。如果你的App中包含UIWebView 或者WKWebView页面，想要自定义统计App中网页界面的事件信息，可以在App中想关的avaScript代码进行事件埋点。
8.1： 针对UIWebView,WKWebView分别在FinishLoad回调中注册Ptengine javascript bridge protocol, 如果使用的是第三方库，可在第三方库相关的抛出的回调中注册该接口。
具体参看接口注释中的代码示例
-
/** * You should register PtAgent javaScript bridge module after webView is finished loading. * We register this bridge module as the properties of javaScript window object. * And then you can invoke the ptmind javaScript API for packing js event for yourself. * @param webView current webView object * * If you are using UIWebView, please invoke this method in delegate method: * - (void)webViewDidFinishLoad:(UIWebView *)webView { * [[PtAgent sharedInstance]PTRegisterJavascriptBridgeForWebView:webView]; * } * If you are using WKWebView, please invoke this method in delegate method: * - (void)webView:(WKWebView *)webView didFinishNavigation:(null_unspecified WKNavigation *)navigation { * [[PtAgent sharedInstance]PTRegisterJavascriptBridgeForWebView:webView]; * } * */ - (void)PTRegisterJavascriptBridgeForWebView:(id)webView;8.2：注册完成之后，还需要针对UIWebView, WKWebView分别在StartLoad相关的回调中过滤掉关于ptengine的请求跳转，我们SDK提供了两个常量PT_WebView_Bridge_Scheme, PT_WebView_Bridge_Host。具体参看接口注释中的代码示例
/** * Parse the web URL request scheme and host info, if they equal to PT_WebView_Bridge_Scheme and PT_WebView_Bridge_Host, * then, DO NOT to navigate URL, just return NO. * @param NSURL: NSURLRequest.URL, WKNavigationAction.request.URL * ************************************************************************************************************************************ * If you are using UIWebView, please invoke this method in this way: * - (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType{ * NSURL *requestURL = [request URL]; * if ([[requestURL scheme] isEqualToString:PT_WebView_Bridge_Scheme] && [[requestURL host] isEqualToString:PT_WebView_Bridge_Host]) { * [[PtAgent sharedInstance]PTJavascriptTrackEventBridgeProtocol:requestURL]; * return NO; * } * * //Your code implementation... * return YES; * } * * If you are using WKWebView, please invoke this method in this way: * - (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler{ * NSURL *requestURL = [navigationAction.request URL]; * if ([[requestURL scheme] isEqualToString:PT_WebView_Bridge_Scheme] && [[requestURL host] isEqualToString:PT_WebView_Bridge_Host]) { * [[PtAgent sharedInstance]PTJavascriptTrackEventBridgeProtocol:requestURL]; * decisionHandler(WKNavigationActionPolicyCancel); * }else { * decisionHandler(WKNavigationActionPolicyAllow); * } * } ************************************************************************************************************************************ * */ - (void)PTJavascriptTrackEventBridgeProtocol:(NSURL *)webRequestURL;8.3： 到此所以配置结束，可以在html中使用javascript接口来埋点事件了，具体参看如下代码示例
* Finally, you can collect your js event with our methods in javascript level. ************************************************************************************************************************************ * We have provided the following APIs for you: * * PtAgentWebViewJSBridge.PTTrackEvent(eventName, eventProperties); * PtAgentWebViewJSBridge.PTPackVirtualPageView(virtualPageViewName, PVProperties); * PtAgentWebViewJSBridge.PTTrackException(exceptionInfo, exceptionCode); * PtAgentWebViewJSBridge.PTBeginEvent(eventName); * PtAgentWebViewJSBridge.PTEndEvent(eventName, eventProperties); * * and recommend you to invoke these methods by this following way: * if (window.PtAgentWebViewJSBridge) { * var attributes = { * 'product': 'English Book', * 'price': 100 * }; * var attributes_json = JSON.stringify(attributes); * PtAgentWebViewJSBridge.PTTrackEvent('TestEventName', attributes_json); * } * * if (window.PtAgentWebViewJSBridge) { * var attributes = { * 'product': 'English Book', * 'price': 100 * }; * var attributes_json = JSON.stringify(attributes); * PtAgentWebViewJSBridge.PTPackVirtualPageView('WebViewDemoPage', attributes_json); * } * * if (window.PtAgentWebViewJSBridge) { * PtAgentWebViewJSBridge.PTTrackException('this is an test error info', 110); * } * * if (window.PtAgentWebViewJSBridge) { * PtAgentWebViewJSBridge.PTBeginEvent('loginTime'); * } * * if (window.PtAgentWebViewJSBridge) { * var attributes = { * 'userName': 'xxxx', * 'email': 'xx@xx.com' * }; * var attributes_json = JSON.stringify(attributes); * PtAgentWebViewJSBridge.PTEndEvent('loginTime', attributes_json); * } * ************************************************************************************************************************************ *
-
9. 日志接口
当集成完SDK后，SDK 调试log默认关闭状态，可通过设置log接口关闭log输出。
/** * Set all level log disabled, default is NO */ - (void)PTEnableLogOutput;
-
10. IDFA声明
由于苹果系统的限制和某些API的不确定性，我们默认采用Advertising Identifier来作为设备的唯一标识，已最大化的保证数据的准确性，所以需要在开发者在上架AppStore时进行关于Advertising Identifier的简单配置：
. 11. iOS SDK 电商模块接口使用说明
11.1
/**
* 用户注册具体信息接口，用于采集用户注册事件。
* pt_xxx字段为协议内定字段，不可随意改变，其他类型字段可根据业务随意变更。
* pt_xxx内定字段需要传哪些请参考协议接口文档中[是否必须]==是 && [传值方式] == 用户
*/
[[PtAgent sharedInstance]PTTrackUserRegister:@{
@"pt_account_id": @"", //内定字段，用户注册的账户信息, 必传
@"pt_gender": @"", //内定字段，用户性别， 选传
@"pt_age": @"", //内定字段，用户年龄， 选传
@"pt_register_country": @"", //内定字段，用户注册时选择的国家信息， 选传
@"pt_register_subdivision": @"", //内定字段，用户注册时选择的国家下属行政地区信息， 选传
@"pt_register_city": @"" //内定字段，用户注册时选择的城市信息， 选传
}
withProperties:@{//用户注册时的自定义变量信息,选传，key为非内定字段，可自定义
@"email": @"pt@ptmind.com",
@"address": @"beijing"
}];
11.2
/**
* 用户登录接口，用于采集用户登录事件。
*/
[[PtAgent sharedInstance]PTTrackUserLogin:@"userid"
withProperties:@{//用户登录时的自定义变量信息,选传，key为非内定字段，可自定义.
@"用户自定义Key1": @"Value1",
@"用户自定义Key2": @"Value2"
}];
11.3
电商事件采集接口
/**
* Use this method to track an event with user-defined value for ecommerce App.
* @param actionCategory, this value can't be nil or empty, category list is:
pt_user_register, pt_user_login, pt_impression, pt_product_detail, pt_add_cart,
pt_remove_cart, pt_check_out, pt_purchase, pt_refund, pt_add_favorite, pt_remove_favorite
* @param productDetails, you MUST pass the specific key-values according to documents for collecting product detail info.
* @param properties, if the specific productDetails can't cover your requirements, you can pass the custom properties info.
************************************************************************************************************************************
* [[PtAgent sharedInstance]PTTrackEventForEcommerce:@"pt_user_register" withProductDetails:@{@"pt_gender":@"man", @"pt_age":@"20", ...} withCustomProperties:@{@"pt_register_properties": {}}];
************************************************************************************************************************************
*/
- (void)PTTrackEventForEcommerce:(PTEcommerceCategory)actionCategory withProductDetails:(NSDictionary *)productDetails withCustomProperties:(nullable NSDictionary *)properties;
Demo示例如下：
NSDictionary *all_products_info = @{
@"pt_account_id": @"", //用户登录的账号id, 选填
@"pt_source": @"", //显示商品展示的来源，比如通过主页，搜索等方式显示出来的。必填
@"pt_ad_creative_id": @"", ///促销活动的 ID（例如 PROMO_1234）。*此字段与 name 字段必须至少设置一个。选填
@"pt_ad_position": @"", //广告素材的位置（例如 banner_slot_1）. 选填
@"pt_promo_info": @"", //促销活动的名称（例如夏季促销).选填
@"pt_promo_properties": @{//与促销活动相关的自定义属性，{}.选填
@"pt_promo_properties_k1": @"pt_promo_properties_v1",
@"pt_promo_properties_k2": @"pt_promo_properties_v2",
},
@"pt_products":@[
@{
@"pt_product_id": @"",//商品ID 或 SKU（例如 P67890）.必填
@"pt_product_name": @"",//商品名称.选填
@"pt_product_brand": @"",//商品品牌.选填
@"pt_product_category": @"",//产品所属的类别（例如服装)，可以使用 / 作为分隔符来指定最多 5 个层级（例如服装/男装/T 恤）。选填
@"pt_product_variant": @"",//产品的细分款式（例如黑色）.选填
@"pt_product_position": @(2),//产品在列表或集合中的位置（例如 2）.选填
@"pt_product_price": @(20.20),//产品的价格（例如 29.20）。选填
@"pt_product_currency_code": "RMB", //产品的货币代码(USD, RMB)，列表参看：https://support.google.com/analytics/answer/6205902?hl=zh-Hans#supported-currencies. 是否必须根据具体接口来定
@"pt_product_coupon": @"", //与产品关联的优惠券代码（例如 SUMMER_SALE13）.选填
@"pt_product_quantity": @(3),//产品数量,选填
@"pt_product_properties": @{//与产品相关的自定义属性，{}. 选填
@"product_key3": @"product_value4",
@"product_key4": @"product_value4"
},
@"pt_product_list":@'search result'//产品在列表或集合(例如搜索结果),选填
}
]
}
NSDictionary *product_info = @{
@"pt_account_id": @"", //用户登录的账号id, 选填
@"pt_source": @"", //显示商品展示的来源，比如通过主页，搜索等方式显示出来的。必填
@"pt_ad_creative_id": @"", ///促销活动的 ID（例如 PROMO_1234）。*此字段与 name 字段必须至少设置一个。选填
@"pt_ad_position": @"", //广告素材的位置（例如 banner_slot_1）. 选填
@"pt_promo_info": @"", //促销活动的名称（例如夏季促销).选填
@"pt_promo_properties": @{//与促销活动相关的自定义属性，{}.选填
@"pt_promo_properties_k1": @"pt_promo_properties_v1",
@"pt_promo_properties_k2": @"pt_promo_properties_v2",
},
@"pt_product_id": @"",//商品ID 或 SKU（例如 P67890）.必填
@"pt_product_name": @"",//商品名称.选填
@"pt_product_brand": @"",//商品品牌.选填
@"pt_product_category": @"",//产品所属的类别（例如服装)，可以使用 / 作为分隔符来指定最多 5 个层级（例如服装/男装/T 恤）。选填
@"pt_product_variant": @"",//产品的细分款式（例如黑色）.选填
@"pt_product_position": @(2),//产品在列表或集合中的位置（例如 2）.选填
@"pt_product_price": @(20.20),//产品的价格（例如 29.20）。选填
@"pt_product_currency_code": @"RMB", //产品的货币代码(USD, RMB)，列表参看：https://support.google.com/analytics/answer/6205902?hl=zh-Hans#supported-currencies. 是否必须根据具体接口来定
@"pt_product_coupon": @"", //与产品关联的优惠券代码（例如 SUMMER_SALE13）.选填
@"pt_product_quantity": @(3),//产品数量,选填
@"pt_product_properties": @{//与产品相关的自定义属性，{}. 选填
@"product_key3": @"product_value4",
@"product_key4": @"product_value4"
},
@"pt_product_list":@'search result'//产品在列表或集合(例如搜索结果),选填
}
//商品展示采集示例
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Impression
withProductDetails:all_products_info
withCustomProperties:@{
@"impress_pro_key1": @"impress_pro_value1",
@"impress_pro_key2": @"impress_pro_value2"
}];
//商品详情采集示例
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Product_Detail
withProductDetails:product_info
withCustomProperties:@{ @"detail_pro_key1": @"detail_pro_value1", @"detail_pro_key2": @"detail_pro_value2" }];
//添加购物车采集示例
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Add_Cart
withProductDetails:product_info
withCustomProperties:@{ @"add_cart_pro_key1": @"add_cart_pro_value1", @"add_cart_pro_key2": @"add_cart_pro_value2" }];
//删除购物车采集示例
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Remove_Cart
withProductDetails:product_info
withCustomProperties:@{ @"remove_cart_pro_key1": @"remove_cart_pro_value1", @"remove_cart_pro_key2": @"remove_cart_pro_value2" }];
//生成订单采集示例
//为当前接口在product_info字典结构中增加以下两个字段的值
NSMutableDictionary * ec_checkout = [NSMutableDictionary new];
[ec_checkout addEntriesFromDictionary:all_products_info];
[ec_checkout setObject:@"pt_order_id_value" forKey:@"pt_order_id"];
[ec_checkout setObject:@(50.33) forKey:@"pt_payment_amount"];
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Check_Out
withProductDetails:ec_checkout
withCustomProperties:@{ @"checkout_pro_key1": @"checkout_pro_value1", @"checkout_pro_key2": @"checkout_pro_value2" }];
//商品购买接口
NSMutableDictionary * ec_purchase = [NSMutableDictionary new];
[ec_purchase addEntriesFromDictionary:all_products_info];
[ec_purchase setObject:@"pt_order_id1111" forKey:@"pt_order_id"];
[ec_purchase setObject:@(50.33) forKey:@"pt_payment_amount"];
[ec_purchase setObject:@"pt_payment_type" forKey:@"pt_payment_type"];
[ec_purchase setObject:@"pt_tax" forKey:@"pt_tax"];
[ec_purchase setObject:@"pt_shipping" forKey:@"pt_shipping"];
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Purchase
withProductDetails:ec_purchase
withCustomProperties:@{ @"pt_purchase_pro_key1": @"pt_purchase_pro_value1", @"pt_purchase_pro_key2": @"pt_purchase_pro_value2" }];
//商品退货采集示例
NSMutableDictionary * ec_refund = [NSMutableDictionary new];
[ec_refund addEntriesFromDictionary:all_products_info];
[ec_refund setObject:@"pt_payment_type" forKey:@"pt_payment_type"];
[ec_refund setObject:@"pt_tax" forKey:@"pt_tax"];
[ec_refund setObject:@"pt_shipping" forKey:@"pt_shipping"];
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Refund
withProductDetails:ec_refund
withCustomProperties:@{ @"pt_refund_pro_key1": @"pt_refund_pro_value1", @"pt_refund_pro_key2": @"pt_refund_pro_value2" }];
//添加收藏夹采集示例
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Add_Favorite
withProductDetails:product_info
withCustomProperties:@{ @"pt_add_favorite_pro_key1": @"pt_add_favorite_pro_value1", @"pt_add_favorite_pro_key2": @"pt_add_favorite_pro_value2" }];
//删除收藏夹采集示例
[[PtAgent sharedInstance]PTTrackEventForEcommerce:PT_Category_Remove_Favorite
withProductDetails:product_info
withCustomProperties:@{ @"pt_remove_favorite_pro_key1": @"pt_remove_favorite_pro_value1", @"pt_remove_favorite_pro_key2": @"pt_remove_favorite_pro_value2" }];