TestBird 崩潰分析(Artisan) iOS SDK 使用指南

最新版本1.04 更新內容

支持H5插件，收集H5 JS異常；
支持Swift語言

1、快速集成

TestBird 崩潰分析(Artisan) iOS SDK，支持iOS 6.0 及以上版本。SDK及Plugin下載

集成具體方法以下:

Step 1. 建立App

• 請註冊TestBird帳戶並登錄產品後臺，點這裏註冊登錄；

• 經過「添加應用」按鈕上傳應用的ipa文件，添加您的新應用；
  

• 添加應用後，在頁面下方的「崩潰分析」面板中獲取您的AppKey，初始化SDK時須要使用；
  

Step 2. 導入SDK

• 下載SDK並解壓，支持收集NSException致使的崩潰和Native崩潰

• 若是您的應用是基於HTML的Hybird App，還能夠下載集成HTML Plugin，支持收集javascript異常

• 將TestBirdAgent.framework拖拽到XCode工程內，並勾選Copy items if need

Step 3. 添加依賴庫

• CoreTelephony.framework

• SystemConfiguration.framework

• Security.framework

• libz.dylib

Step 4. 導入頭文件

• Objective-C，在 AppDelegate.m 中添加：

  #import <TestBirdAgent/TestBirdAgent.h>

• Swift，請在 bridging-header.h 文件中導入頭文件

Step 5. 初始化SDK

在 AppDelegate 的 application didFinishLaunchWithOptions 方法中添加SDK初始化語句：

• Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        // 配置打開SDK調試模式，默認是關閉狀態
        [TestBirdAgent setDebug:YES];

        // 初始化SDK
        [TestBirdAgent enableWithAppKey:@"YourAppKey"]; // YourAppKey 是在官網申請到的App Key
        return YES;
    }

• Swift

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        TestBirdAgent.setDebug(true)
        TestBirdAgent.enableWithAppKey("YourAppKey") // YourAppKey 是在官網申請到的App Key
    }

注意：請先關閉其餘第三方SDK的崩潰捕獲接口，而後再初始化TestBird SDK，或將TestBird SDK初始化代碼放到 didFinishLaunchWithOptions 方法最後，避免衝突。

2、SDK調試

SDK處於調試狀態下，在APP啓動以後，若是在設備日誌輸出中能夠找到如下Log，就代表SDK初始化成功：

TestBird: CrashReporter enabled!
TestBird: framework bundle identifier: com.testbird.artisan.TestBirdAgent
TestBird: framework version: x.x.x

爲確保SDK正常工做，請觸發一次崩潰，並檢查日誌和Web分析報表

注意：多數時候須要重啓一次應用，崩潰信息纔可以上報成功

3、上傳符號化文件

符號表是內存地址與函數名、文件名、行號的映射表。爲了能快速並準確地定位用戶APP發生崩潰等異常的代碼位置，TestBird須要使用符號表對APP發生異常的程序錯誤堆棧進行解析和還原。

3.1 符號化文件的位置

在執行archive以後，能夠在生成的「.xcarchive」文件夾中找到dSYMs的文件夾， 在dSYMs文件夾中有一個名爲{APP_NAME}.app.dSYM的文件（APP_NAME是應用的名字），這個文件裏面就包含了咱們須要的符號表。

注意：若是發現這個位置沒有 dSYM 文件，說明設置了打包時不生成符號表。可查看Build Settings -> Build Options -> Debug Information Format 的設置，必須選擇DWARF with dSYM File纔會生成符號表文件。

3.2 上傳符號化文件

將符號化文件{APP_NAME}.app.dSYM壓縮成zip包，經過崩潰分析應用設置中的「版本管理」上傳。

注意：各個版本須要分別上傳符號化文件。

3.3 Bitcode APP的符號化文件

開啓了Bitcode的APP須要在XCode中下載符號化文件，具體方法以下：

• 打開XCode的Organizer窗口，選擇要對應的archive。

• 再點擊「Dowload dSYMs」，符號化文件會被下載到對應的archive目錄。

• 將對應的dSYM文件打包上傳。

4、API 說明

4.1 啓用崩潰報告功能

啓用TestBirdAgent，並建立一個TestBirdAgent的實例，註冊的APP Key

• Objective-c

+ (TestBirdAgent *)enableWithAppKey:(NSString *)appKey;

• Swift

TestBirdAgent.enableWithAppKey(appKey: String) -> TestBirdAgent

4.2 獲取 TestBirdAgent 的全局惟一實例

• Objective-c

+ (TestBirdAgent *)sharedInstance;

• Swift

TestBirdAgent.sharedInstance() -> TestBirdAgent

4.3 設置User ID

調用該方法，設置當前使用App的用戶帳號，以便跟蹤用戶反饋，找出對應的崩潰或異常。

• Objective-c

- (void)setUserId:(NSString *)userId;

• Swift

setUserId(userId: String)

4.4 自定義Log日誌

調用該方法，添加一條自定義Log日誌，該Log會隨崩潰堆棧等信息收集到崩潰報表中。自定義Log日誌緩存Buffer是32KB，超出時只保留最新的Log。

• Objective-c

-(void)addCustomLog:(NSString *)log;

• Swift

addOneCustomLog(log: String!)

4.5 自定義鍵值對參數

添加自定義鍵值對參數

調用該方法後，將向緩存中添加一條鍵值對參數，參數將會被收集到崩潰報表中。鍵和值的總大小不能超過1KB，最多設置32條自定義鍵值對。

• Objective-c

- (BOOL)setCustomValue:(NSString *)value forKey:(NSString *)key;

• Swift

setCustomValue(value: String!, forKey: String!)

移除自定義鍵值對

• Objective-c

- (BOOL)removeCustomKey:(NSString *)key;

• Swift

removeCustomKey(key: String!)

清除全部自定義鍵值對

• Objective-c

- (void)clearCustomKeys;

• Swift

clearCustomKeys()

4.6 設置Debug模式

將SDK設置爲debug模式後，TestBirdAgent會輸出調試Log，默認爲關閉狀態。

• Objective-c

- (void)setDebug:(BOOL)enable;

• Swift

setDebug(enable: Bool)

4.7 上報NSException

能夠經過該API手動上報NSException。手動上報的NSException將單獨顯示在分析報表的「異常」欄目中。

• Objective-c

- (void)reportException:(NSException *)exception;

• Swift

// unsupported yet

4.8 HTTPs開關

默認狀況下SDK將使用HTTPs和服務器通訊，若是須要使用非HTTPs的通訊請在初始化SDKenablWithAppKey以前調用如下 接口（參數爲NO，表示禁用HTTPs傳輸）

• Objective-c

- (void)enableSecurityTransport:(BOOL)enable;

• Swift

enableSecurityTransport(enable: Bool)

HTTP通訊配置，iOS 9要求默認使用HTTPs通訊。TestBird目前支持HTTPs 和 HTTP 兩種鏈接方式，若是要使用HTTP鏈接，請在Info.plist中，按照下圖添加容許TestBird域名HTTP通訊的配置：

也能夠，添加容許任意域名HTTP通訊的配置：