IOS 之Google Analytics SDK预研---API

后续的文章都是根据IOS SDK进行介绍，如果WEB，ANDROID的读者可自行在https://developers.google.com/analytics/上找到相应的SDK API帮助进行查看。

谷哥的GA  SDK中的API并不多，很少。主要就5个头文件和一个库文件。

• GAI.h
• GAITracker.h
• GAITrackedViewController.h
• GAITransaction.h
• GAITransactionItem.h
• libGoogleAnalytics.a

先来看一下GAI.h这个是GA的分析对象，是一个单例。它能干什么，有什么接口？

@interface GAI : NSObject

@property(nonatomic, assign) id<GAITracker> defaultTracker;

@property(nonatomic, assign) BOOL debug;

@property(nonatomic, assign) BOOL optOut;

@property(nonatomic, assign) NSTimeInterval dispatchInterval;

@property(nonatomic, assign) BOOL trackUncaughtExceptions;

+ (GAI *)sharedInstance;

- (id<GAITracker>)trackerWithTrackingId:(NSString *)trackingId;

- (void)dispatch;

@end

此对象只有三个方法其中一个是类方法（静态方法）这里就说了， 其中- (id<GAITracker>)trackerWithTrackingId:(NSString *)trackingId; 这句很重要，通过前一章介绍得到的跟踪ID来产生一个跟踪实例。eg:

id<GAITracker> tracker = [[GAI sharedInstance] trackerWithTrackingId:@"UA-YOUR-TRACKING-ID"];

再看有几个属性：

defaultTracker 默认跟踪对象，初值为NIL，必须调用trackerWithTrackingId进行初始化，这时产生的tracker 将会被后面的GAITrackedViewController中的跟踪实例进行使用。

debug ：SDK的调试信息开关，默认为关，如果开启，则在调试输出栏里可以看到SDK运行过程中的日志。建议调时的时候设为YES，在发布的时候设为NO，这样可以优化性能。通过调用setDebug方法进行设置

optOut：跟踪退出开关，默认为FALSE，当设为TRUE时，此时SDK跟踪队列中的信息将停止向GA发送数据，该标识一次设置将对整个应该实例的生命周期有效，此值不保存的，即重起后，只要不设为TRUE，则此标识仍是FALSE。通过调用setOptOut进行设置。

dispatchInterval :跟踪信息递送周期，默认为2分钟，即每隔两分钟进行POST一次跟踪数据到GA，可根据自己的项目进行设置值，调用setDispatchInterval进行设置。如果特殊情况要手动POST消息到GA（如异常退出时或退出应该前要保存一次到GA），直接调用dispatch方法。设置了该值之后，系统就自动按间隔进行POST，这个不受前台，后台的影响。

trackUncaughtExceptions ： GA SDK的异常捕获，默认为FALSE，当为TRUE时，则开启SDK的异常捕获。如果SDK中产生了异常则进行捕获。

GAITrackedViewController.h

@interface GAITrackedViewController : UIViewController {
 @private
  id<GAITracker>  tracker_;
  NSString        *trackedViewName_;
}

/*!
 The tracker on which view tracking calls are be made, or `nil`, in which case
 [GAI defaultTracker] will be used.
 */
@property(nonatomic, assign) id<GAITracker> tracker;

@property(nonatomic, copy)   NSString *trackedViewName;

@end

这个文件中的类主要作用是用于跟踪页面信息，其继承于UIViewController，以前我们的Controller都是继承UIViewController的，而如果你需要跟踪页面的信息，还是得将Controller继承于GAITrackedViewController 这个类。 其次类中只有两个属性一个是跟踪ID的对象，可以通过[GAI defaultTracker]进行赋值，其次一个就是页面信息，通常用于跟踪记录当前程序是否进入到此界面了，这样来回切换或重构时，就可以知道用户最终对某个页面的浏览次数，从而分析用户是否喜欢某个界面。

GAITransaction.h

电子商务信息类

@interface GAITransaction : NSObject

@property(nonatomic, copy, readonly) NSString *transactionId;

@property(nonatomic, copy, readonly) NSString *affiliation;

@property(nonatomic, assign) int64_t revenueMicros;

@property(nonatomic, assign) int64_t taxMicros;

@property(nonatomic, assign) int64_t shippingMicros;

@property(nonatomic, readonly) NSArray *items;


+ (GAITransaction *)transactionWithId:(NSString *)transactionId
                      withAffiliation:(NSString *)affiliation;


- (void)addItem:(GAITransactionItem *)item;

- (void)addItemWithCode:(NSString *)productCode
                   name:(NSString *)productName
               category:(NSString *)productCategory
            priceMicros:(int64_t)priceMicros
               quantity:(NSInteger)quantity;

@end

这个其实是一个电子商务的数据结构，主要是承载一般电子商务的必要信息，将这些信息发送到GA进行分析罢了。

引入SDK的例子：

- (void)onPurchaseCompleted {
  GAITransaction *transaction =
      [GAITransaction transactionWithId:@"0_123456"            // (NSString) Transaction ID, should be unique.
                        withAffiliation:@"In-App Store";       // (NSString) Affiliation
  transaction.taxMicros = (int64_t)(0.17 * 1000000);           // (int64_t) Total tax (in micros)
  transaction.shippingMicros = (int64_t)(0);                   // (int64_t) Total shipping (in micros)
  transaction.revenueMicros = (int64_t)(2.16 * 1000000);       // (int64_t) Total revenue (in micros)

  [transaction addItemWithSKU:@"L_789"                         // (NSString) Product SKU
                         name:@"Level Pack: Space"             // (NSString) Product name
                     category:@"Game expansions"               // (NSString) Product category
                  priceMicros:(int64_t)(1.99 * 1000000)        // (int64_t)  Product price (in micros)
                     quantity:1];                              // (NSInteger)  Product quantity

  [[GAI sharedInstance].defaultTracker sendTransaction:transaction]; // Send the transaction.
}

这里要注意的是三个int属性在设置值时扩大100万倍，可能是数值大小时，在分析工具上画出的线条不明显吧，官网中有说： For example, to send a currency value of  4.5991 , you should convert that value to micros (i.e.  4599100 ) when you send the transaction to Google Analytics, as in the examples above. When the SDK dispatches that transaction to Google Analytics, that value is automatically converted into a fixed-point decimal value and sent as  4.5991 .

GAITransactionItem.h

这个就不哆嗦了，这个只是一个子集的结构。

下面主要讲GA SDK的核心API：

GAITracker.h

此类主要完成了，将跟踪数据上传到GA平台。

@protocol GAITracker<NSObject>


@property(nonatomic, copy, readonly) NSString *trackingId;

@property(nonatomic, copy) NSString *appName;

@property(nonatomic, copy) NSString *appId;

@property(nonatomic, copy) NSString *appVersion;

@property(nonatomic, assign) BOOL anonymize;

@property(nonatomic, assign) BOOL useHttps;

@property(nonatomic, assign) double sampleRate;

@property(nonatomic, copy, readonly) NSString *clientId;

@property(nonatomic, copy) NSString *appScreen;

@property(nonatomic, copy) NSString *referrerUrl;

@property(nonatomic, copy) NSString *campaignUrl;

@property(nonatomic, assign) BOOL sessionStart;

@property(nonatomic, assign) NSTimeInterval sessionTimeout;

- (BOOL)sendView;

- (BOOL)trackView;//此API 补废弃，只在旧的SDK中使用

- (BOOL)sendView:(NSString *)screen;

- (BOOL)trackView:(NSString *)screen;//此API 补废弃，只在旧的SDK中使用


- (BOOL)sendEventWithCategory:(NSString *)category
                   withAction:(NSString *)action
                    withLabel:(NSString *)label
                    withValue:(NSNumber *)value;

//此API 补废弃，只在旧的SDK中使用
- (BOOL)trackEventWithCategory:(NSString *)category withAction:(NSString *)action withLabel:(NSString *)label withValue:(NSNumber *)value;- (BOOL)sendTransaction:(GAITransaction *)transaction;
//此API 补废弃，只在旧的SDK中使用
- (BOOL)trackTransaction:(GAITransaction
 *)transaction;- (BOOL)sendException:(BOOL)isFatal withDescription:(NSString *)format, ...;
//此API 补废弃，只在旧的SDK中使用
- (BOOL)trackException:(BOOL)isFatal withDescription:(NSString *)format, ...;- (BOOL)sendException:(BOOL)isFatal withNSException:(NSException *)exception;
//此API 补废弃，只在旧的SDK中使用
-
 (BOOL)trackException:(BOOL)isFatal withNSException:(NSException *)exception;- (BOOL)sendException:(BOOL)isFatal withNSError:(NSError *)error;
//此API 补废弃，只在旧的SDK中使用
- (BOOL)trackException:(BOOL)isFatal withNSError:(NSError *)error;- (BOOL)sendTimingWithCategory:(NSString
 *)category withValue:(NSTimeInterval)time withName:(NSString *)name withLabel:(NSString *)label;
//此API 补废弃，只在旧的SDK中使用
- (BOOL)trackTimingWithCategory:(NSString *)category withValue:(NSTimeInterval)time withName:(NSString *)name withLabel:(NSString *)label;- (BOOL)sendSocial:(NSString
 *)network withAction:(NSString *)action withTarget:(NSString *)target;
//此API 补废弃，只在旧的SDK中使用
- (BOOL)trackSocial:(NSString *)network withAction:(NSString *)action withTarget:(NSString *)target;- (BOOL)set:(NSString *)parameterName value:(NSString *)value;-
 (NSString *)get:(NSString *)parameterName;


- (BOOL)send:(NSString *)trackType
      params:(NSDictionary *)parameters;

- (BOOL)setCustom:(NSInteger)index
        dimension:(NSString *)dimension;

- (BOOL)setCustom:(NSInteger)index
           metric:(NSNumber *)metric;

- (void)close;
@end






先对属性进行介绍：
trackingId  
 // 跟踪ID，只读。

appName   
  //应该程序名

appId        
  //AppId

appVersion 
  //应用程序版本号

anonymize 
 //是否匿名发送，即发送到GA时使用匿名，这个跟用户隐私有关，有些国家对IP有监控，默认为FALSE 

useHttps 
 //是否使用HTTPS传输，默认为YES

sampleRate          // 设置采样速率，即每隔多长时间进行采样。

clientId                    //客户端ID，是一个唯一ID，在应用第一次使用时生成，除非全新安装，否则生成的ID将不会改变。

appScreen 
//应该屏幕，当调用sendView的时候会被进行赋值操作。

referrerUrl 
//访问来源，即可以跟踪从哪个网站访问到自己的应该用。比如WEB上用来跟踪流量来源。

campaignUrl         //营销广告活动URL，


 
 
广告系列来源 (utm_source)
必填。使用 utm_source 标识搜索引擎、简报名称或其他来源。

示例：utm_source=google
广告系列媒介 (utm_medium)
必填。使用 utm_medium 标识媒介，例如电子邮件或每次点击费用广告。

示例：utm_medium=cpc
广告系列字词 (utm_term)
用于付费搜索。使用 utm_term 来注明此广告的关键字。

示例：utm_term=running+shoes
广告系列内容 (utm_content)
用于 A/B 测试和在展示广告网络投放的广告。使用 utm_content 区分指向同一网址的广告或链接。

示例：utm_content=logolink 或 utm_content=textlink
广告系列名称 (utm_campaign)
用于关键字分析。使用 utm_campaign 来标识特定的产品促销活动或战略性广告系列。

示例：utm_campaign=spring_sale


基本格式：http://www.eastdesign.net/?utm_source=eastdesign&utm_medium=banner&utm_campaign=Eastern-AD-Campaign

参数前面域名部份为广告连地址。



sessionStart          //会话开始

sessionTimeout    //会话的超时时间。


              

属性介绍完成，下面讲解一下成员函数：
- (BOOL)sendView;
函数作用：判断调用sendView是否成功，通常在异步操作的时候有用
返回值：TRUE or FALSE;


- (BOOL)sendView:(NSString *)screen;
函数作用：发送一上页面名称，名称自己定义，用于分析跟踪。
入参: 页面名称
返回值：TRUE OR FALSE
eg:
- (void)viewDidLoad
{
    [super viewDidLoad];
	// Do any additional setup after loading the view, typically from a nib.
    self.trackedViewName = @"page tracker : Main view"; //[self.tracker sendView:@"page tracker : Main view"];
    
    UIBarButtonItem *rightButton = [[UIBarButtonItem alloc] initWithTitle:@"Right" style:UIBarButtonItemStylePlain target:self action:@selector(RightAction)];  
    self.navigationItem.rightBarButtonItem = rightButton;
    
}
在分析平台上可以看到：






- (BOOL)sendEventWithCategory:(NSString *)category

                   withAction:(NSString *)action

                    withLabel:(NSString *)label

                    withValue:(NSNumber *)value;
函数作用：发送事件跟踪，比哪点击事件，拖动事件，TOUCH事件等。
入参category：事件的类别。
入参action:事件的动作，如安下，弹起，拖动，或在屏幕上移动等。
入参label ：引发事件的标签，比如此事件是由哪个BUTTON或LABEL或TextView等发起的。
入参value：引发事件传递的值。当然这个值是用于跟踪而具体设的了。
返回值：TRUE OR FALSE
eg:
- (IBAction)OnbtnTestclicked:(id)sender {

    //事件的跟踪
    BOOL ok = [self.tracker sendEventWithCategory:@"UIACTION"
                                       withAction:@"btnOnPress"
                                        withLabel:@"title"//[(UIButton*)sender titleLabel].text
                                        withValue:[NSNumber numberWithInt:100]];
    if (ok) {
        NSLog(@"Send Event OK");
    }
}




- (BOOL)sendTransaction:(GAITransaction *)transaction;
函数说明：发送电子商务结构信息。
入参：为一个电子商务的结构体， 前面有谈到。
返回值：TRUE OR FALSE
事例参见文章前部份。



- (BOOL)sendException:(BOOL)isFatal

      withDescription:(NSString *)format, ...;

- (BOOL)sendException:(BOOL)isFatal

      withNSException:(NSException *)exception;

- (BOOL)sendException:(BOOL)isFatal

          withNSError:(NSError *)error;
函数说明：以上三个都是发送异常或crash信息。分别重载了三种不同参的方法。方便用户跟踪。
入参isFatal：BOOL型，当设为YES时，表示这为至命异常，也就是说在调用前必须知道此处可能引发至命异常，则跟踪时设为YES，一般情况的异常就设为NO。
入参exception：异常对象，即由系统抛出的异常信息进行跟踪。
入参Error：即使用错误信息进行跟踪。
入参format：允许用户进行自定义异常信息的跟踪。
返回值：TRUE OR FALSE
eg:例子中我故事伪造异常来进行捕捉。
- (IBAction)onBtnexptClicked:(id)sender {
#define B
    BOOL ok = false;
#ifdef  A
    @try
    {
        NSArray *arr = {@"I",@"LOVE",@"U",nil};
        NSString * str = [arr objectAtIndex:4];
        NSLog(str);
    }
    @catch (NSException *e) {
        //No 跟踪的是非至命异常，true时，为至命异常
        ok = [self.tracker sendException:NO withNSException:e];

    }
#endif
#ifdef B
    @try
    {
        NSArray *arr = {@"I",@"LOVE",@"U",nil};
        NSString * str = [arr objectAtIndex:4];
        NSLog(str);
    }
    @catch (NSException *e) {
        //No 跟踪的是非至命异常，true时，为至命异常
        ok =[self.tracker sendException:NO withDescription:@"xxx %@,code = %d",@"testError",100];
    }
#else
    NSError *err = nil;
    if (!err) {
        ok = [self.tracker sendException:NO withNSError:err];
    }
#endif
    
    if (ok) {
        NSLog(@"Send exception OK");
    }
}





- (BOOL)sendTimingWithCategory:(NSString *)category

                     withValue:(NSTimeInterval)time

                      withName:(NSString *)name

                     withLabel:(NSString *)label;
函数说明：发送用户定时数据。
入参category：定时的目录.
入参time :定时的间隔值。
入参name:使用定时的名称
入参label:什么标签使用了定时。
返回值：TRUE OR FALSE
eg:

- (void)onLoad:(NSTimeInterval *)loadTime {
    [tracker sendTimingWithCategory:@"resources"
                            withTimeInterval:loadTime
                                    withName:@"high scores"
                                   withLabel:nil];
    ... // The rest of your onLoad: code.
}





- (BOOL)sendSocial:(NSString *)network

        withAction:(NSString *)action

        withTarget:(NSString *)target;
函数作用：发送社交网络跟踪信息，比如国外的facebook,twitter,国内的人人网，新浪博客等。
入参network：社交的名称
入参action：要进行社交的动作。
入参target ：要对哪个社交进行活动跟踪。
返回值：TRUE OR FALSE



eg

[tracker sendSocial:@"Twitter"
          withAction:@"Tweet"
          withTarget:@"https://developers.google.com/analytics"];  // Send social interaction.
- (BOOL)set:(NSString *)parameterName

      value:(NSString *)value;

函数作用：给tracker设置一个参数名称，以便于区别是哪个tracker。
入参parameterName：参数的名称。
入参value：参数名对应的值。
返值：TRUE OR FALSE




- (NSString *)get:(NSString *)parameterName;

函数作用：通过参数名获取相应的参数值，如果获取不到返回NIL

返回值：STRING ，成功为参数名对应的值，失败或未设置时为NIL。





- (BOOL)send:(NSString *)trackType

      params:(NSDictionary *)parameters;
函数作用：用于跟踪自定义tracker类型的信息。
入参trackType：跟踪类型，自定义的，如@"appview"
入参params：此为一个字典类型变量，Key-vlaue模式。用来携带该跟踪类型的信息，自行跟踪想要什么就往字典中放。
返回值：TRUE OR FALSE，成功则发到GA，失败则有可能是trackerType 查询失败。





- (BOOL)setCustom:(NSInteger)index

        dimension:(NSString *)dimension;
函数作用：设置跟踪信息的指标值。
入参index：指标的索引，从1开始。
dimension：需要跟踪的指标名称，自定义。
返回TRUE OR FALSE
eg:

id tracker = [[GAI sharedInstance].defaultTracker;  // Get the tracker object.
[tracker setCustom:1
         dimension:@"myValue"];  // Set the dimension value for index 1.
[tracker sendView:screenName];  // Dimension value is associated and sent with this hit.
#import "myViewController.h"
#import "GAI.h"

@implementation myViewController

-(void)viewDidAppear
{
    id tracker = [[GAI sharedInstance].defaultTracker;  // Get the tracker object.
    [tracker setCustom:1
             dimension:@"myValue"];  // Set the custom dimension value.
    [super viewDidAppear:animated]   // Custom dimension value will be sent with the screen view.

}

// The remainder of the implementation is omitted.







- (BOOL)setCustom:(NSInteger)index

           metric:(NSNumber *)metric;

函数作用：设置跟踪信息的维度值。

入参index：维度的索引值，从1开始。
入参metric：一个64位长的整型值，用于记录维度值。
返回：TRUE OR FALSE
eg

id tracker = [[GAI sharedInstance].defaultTracker;  // Get the tracker object.
[tracker setCustom:1
         metric:[NSNumber numberWithLongLong:1]];  // Increment the metric at index 1.
[tracker sendView:screenName];                    // Metric value sent with this hit.




- (void)close;


函数作用：关闭tracker跟踪器。
通常很少手动调用此方法。



到此整个IOS的GA  SDK介绍完成，相信大家通过以上的介绍可以进行初步的使用了，对于GA的平台分析，大家还是要多在项目中进行有效的跟踪才好分析出我们最终想要的数据啊，光有SDK不能说明问题，需要好要的跟踪过程，即在什么地方进行跟踪，在哪个位置跟踪比较理想，等这些都是根据项目实际进行的。好了，大家着手试一下吧。
至于怎么在IOS中使用就不用说了吧，就是把哪几个头文件和LIB库引进来就可以了，他的lib库依赖了coredata.framework及Systemconfigation.frawework，所以也要引入这两个库。



下一节，以当前的实际项目，如果把这个GA SDK，适配到项目中进行使用。
多谢各位读者。