Upsight iOS SDK

####手动集成 首先，您需要在您的机器上存储 UpsightKit 框架

1. 将 UpsightKit 框架添加到应用的构建阶段区块中的目标设置。另外，添加 Apple 提供的 CoreTelephony 和 AdSupport 框架。
2. 在“信息”区块的目标属性中，添加 UpsightAppToken 和 UpsightAppSecret。这些属性为 string 类型，在您添加应用时在 Upsight 控制面板上提供。
3. 在目标构建设置的构建设置中，将 -ObjC 添加到其他链接器标志字段。

#####Xcode 文档 Upsight iOS SDK 使用 appledoc 生成以 HTML 形式展示的引人注目的 API 方法文档。这些文档是完全索引和可浏览的。

在手动集成 UpsightKit 框架时，您可以选择安装 Upsight 文档，以便在 Xcode 中可用。为了做到这一点，解压缩 iOS SDK 压缩文件 并运行以下命令

$ ./install_docsets.sh

注意：如果没有安装任何文档，将无法安装 Upsight 文档。如果安装过程失败，请转到 Xcode 设置中的“下载”部分并下载其他文档模块。然后再次运行脚本。

要查看 Upsight 文档，请点击帮助 > 文档和 API 参考。在左侧，您将找到 UpsightKit 文档。

####CocoaPods 集成 使用 CocoaPods 是将 SDK 集成到项目中最简单的方法。只需在 Podfile 中添加 pod 'UpsightKit' 即可。以下是一个包含两个目标（iOS 和 tvOS 应用）的 Podfile 示例

target 'MyiOSApp' do
    platform :ios, '8.0'
    pod 'UpsightKit', '~> 4.0.5'
end

target 'MyTvOSApp' do
    platform :tvos, '9.1'
    pod 'UpsightKit', '~> 4.0.5'
end

####调试 首先，打开完全调试日志

1. 在 AppDelegate.m 文件的顶部添加 #import <UpsightKit/UpsightKit.h>
2. 在 application:didFinishLoadingWithOptions: 中添加 [Upsight setDefaultLogLevel:UpsightLoggerLevelDebug]; 这将让您能够在确认集成时看到 SDK 的调试输出。一旦您完成集成，就可以删除此行。

现在您运行应用，您将在 XCode 的调试控制台中看到调试输出，显示 SDK 活动情况。

到此为止

• 运行应用程序将生成一个 "upsight.config.expired" 信息。
• 服务器将对这条消息发送响应。响应体定义了SDK的配置。您可以在调试控制台中看到响应的JSON。

会话正在被跟踪，并将提供基于会话的指标。

• 启动应用程序将生成一个 "upsight.session.start" 消息。
• 隐藏应用程序将生成一个 "upsight.session.pause" 消息。
• 当应用程序返回前台时，如果背景时间小于配置的会话间隔时间（由服务器设置），则生成一个 "upsight.session.resume" 消息。否则，发送一个新的 "upsight.session.start" 消息，并更新会话ID。
• 这些信息将批量发送：它们不会立即显示在仪表板上。当发送事件批次的时，您将在调试窗口中看到这样的消息："批量队列正向端点发送批次：http://batch.upsight-api.com/batch/v1/"

####添加自定义事件

1. 在您的main视图控制器的.m文件中，添加 #import <UpsightKit/UpsightKit.h>
2. 在您想要发送事件的点，添加

[Upsight recordAnalyticsEventWithName:@"myApp.myEvent.name" properties:nil];

现在调试控制台将显示事件已被存储。请注意，直到积累足够多的事件，或者消息批次达到一定年龄，消息实际上不会被发送到服务器。

位置

启用位置跟踪将允许您根据用户的地理位置进行目标定位和细分数据。这些数据将附加到从设备发送的所有事件。要向SDK提供位置数据，首先在您的应用程序中配置位置服务。

CLLocationManager *locationManager = [[CLLocationManager alloc] init];
locationManager.delegate = self; // something that implements CLLocationManagerDelegate
locationManager.desiredAccuracy = kCLLocationAccuracyBest;
locationManager.distanceFilter = 1.0;
if ([self.locationManager respondsToSelector:@selector(requestWhenInUseAuthorization)]) {
    [self.locationManager requestWhenInUseAuthorization];
}
[locationManager startUpdatingLocation];

然后实现以下 CLLocationManagerDelegate 方法。

- (void)locationManager:(CLLocationManager *)manager didUpdateLocations:(NSArray *)locations
{
    CLLocation *location = [locations firstObject];
    [Upsight setLocation:location];
}

最后，在您应用程序的info.plist文件中添加一个带有 NSLocationWhenInUseUsageDescription 键的行，并将值设置为当请求用户授权使用其位置数据时，应用程序要显示给用户的文本。

提供给SDK的位置数据将一直使用，直到更新或直到用户的会话结束（应用程序被置于后台超过两分钟，或由推送通知从后台唤醒）。

良好做法是一次只启用一个CLLocationManager的实例。当一个CLLocationManager实例超出范围时，您将停止接收到位置更新，通常它被保存为一个活动对象实例中的属性。

还应将 desiredAccuracy 设置为尽可能低的值，同时还能实现您应用程序的目的。这是为了防止过度使用系统资源。

用户属性

用户属性是您定义并且在发送到 Upsight 服务器的每个事件中都出现的属性。您必须首先在项目设置的 Info 部分定义这些属性。

1. 将新行添加到您的项目信息列表中，并命名为 UpsightUserAttributes
2. 将新行的类型设置为 Dictionary
3. 点击 UpsightUserAttributes 左侧的展开箭头
4. 为要包含的每个用户属性添加一个新行，并为每个属性提供一个名称、类型和默认值

在您的代码中，您可以检索和设置您创建的用户属性的值。您可以通过名称访问它们。假设您已经使用前面的步骤创建了两个属性，分别称为 "myNumberAttribute" 和 "myStringAttribute"，类型分别为 Number 和 String，您将使用以下方式检索它们的值

NSNumber *aNumber = [USUserAttributes numberForKey:@"myNumberAttribute"];
NSString *aString = [USUserAttributes stringForKey:@"myStringAttribute"];
NSString *aDate = [USUserAttributes dateForKey:@"myDateAttribute"];
BOOL aBool = [USUserAttributes boolForKey:@"myBooleanAttribute"];	

这将返回在信息设置中定义的默认值，除非您更改这些值，如下所示

[USUserAttributes setNumber:@(10) forKey:@"myNumberAttribute"];
[USUserAttributes setString:@"aString" forKey:@"myStringAttribute"];
[USUserAttributes setDate:[NSDate date] forKey:@"myDateAttribute"];
[USUserAttributes setBool:NO forKey:@"myBooleanAttribute"];

现在，NSNumber *aNumber = [USUserAttributes numberForKey:@"myNumberAttribute"]; 将返回 10，NSString *aString = [USUserAttributes stringForKey:@"myStringAttribute"]; 将返回 aString，[USUserAttributes dateForKey:@"myDateAttribute"] 将返回调用 setDate:forKey: 方法的日期和时间，而 BOOL aBool = [USUserAttributes boolForKey:@"myBooleanAttribute"] 将返回 NO。

请注意，您不能以编程方式添加或删除用户属性。它们必须通过信息设置添加和删除。添加和删除用户属性将在 Upsight 服务器上存储的数据中造成不连续性，因此您应该慎重考虑和计划后执行此操作。

####里程碑

里程碑有一个必填属性 - “作用域”，它独特地描述了应用程序中的该位置。例如，“作用域”可以是 "main_menu"、"inventory" 或 "level_up"。

[Upsight recordMilestoneEventForScope:@"main_menu"];

####显示内容

显示营销内容需要“广告牌”。广告牌就像是 SDK 可以放置从服务器接收到的内容的空框。与里程碑事件一样，每个广告牌都与一个 作用域 关联。里程碑事件返回的内容将与里程碑相同的 作用域。

显示内容的三个基本步骤如下

2. 将 USBillboardDelegate 协议添加到您的类之一中，并实现 presentingViewControllerForBillboard:
3. 获取您想要显示内容的 作用域 的 USBillboard 对象，并将其实例属性设置为指向步骤 1 中的类的对象。
4. 为作用域记录里程碑事件。

通过更改代码执行步骤 2 和步骤 3 的时间，您可以控制内容何时显示。步骤 2 和步骤 3 不需要按特定顺序执行，并且内容只有在两个步骤都已执行后才会显示。

######示例 1：在视图中显示广告牌

@interface ViewController () <USBillboardDelegate>

更改 ViewController 的接口定义以指示它实现了 USBillboardDelegate。这需要在 .m 文件顶部 ViewController 的 @interface 指令的末尾添加 <USBillboardDelegate>

-(UIViewController *)presentingViewControllerForBillboard:(id<USBillboard>)aBillboard
{
	return self;
}

添加以下方法

id <USBillboard> billboard = [Upsight billboardForScope:@“<your scope name>”];  
billboard.delegate = self;

在 ViewController 的 viewDidLoad: 方法中获取您的 作用域 的 USBillboard

[Upsight recordMilestoneEventForScope:@“<your scope name>”];  

最后，发送里程碑

######示例 2：在自定义类中显示广告牌

@implementation MyClass

- (instancetype)init
{
    self = [super init];
    if (nil != self) {
        
        // Get the billboard for the scope
        id<USBillboard> billboard = [Upsight billboardForScope:@"SomethingInteresting"];
        
        // Set this object as the billboard's delegate
        // so the billboard can call presentingViewControllerForBillboard:
        billboard.delegate = self;
    }
    return self;
}


- (void)anInterestingMethod
{
    // Send a Milestone event here because something intersting happened
    [Upsight recordMilestoneEventForScope:@"SomethingInteresting"];
}


#pragma mark USBillboardDelegate methods

- (UIViewController *)presentingViewControllerForBillboard:(id<USBillboard>)aBillboard
{
    UIViewController *topController = [UIApplication sharedApplication].keyWindow.rootViewController;
    
    while (topController.presentedViewController) {
        topController = topController.presentedViewController;
    }
    
    return topController;
}

@end

注意：当您不再希望给定广告牌显示内容时，应将其委托设置回 nil;

如果您想检查是否有内容准备好在特定范围内显示，请调用该范围的海报上的isContentReady方法。

if (YES == [Upsight billboardForScope:self.currentScope].isContentReady) {
    // Take action
}

对虚拟商品促销和奖励的反应

奖励和虚拟商品促销（VGP）是通过仪表板设置并显示在海报上的两种内容类型。它们与其他内容单元不同之处在于，作为程序员，您需要知道客户是否接受了这个优惠。

如果您的用户收到奖励或同意购买虚拟商品，您会通过海报委托协议的两种可选方法之一得到通知。

- (void)billboard:(id<USBillboard>)aBillboard didReceiveReward:(id<USReward>)aReward;
- (void)billboard:(id<USBillboard>)aBillboard didReceivePurchase:(id<USPurchase>)aPurchase;

通过提供其中一个或两个方法的实现，您的代码将有机会根据用户的操作采取适当的行动。

在VGP的情况下，您可能需要在用户和苹果的App Store之间进行交易。一旦交易完成，您可以使用InAppPurchase事件来跟踪结果。

####跟踪货币化有两种单独的事件跟踪货币化。如果您想跟踪通过App Store进行的购买，请使用Upsight类中的以下方法：

+ (void)recordInAppPurchaseEventWithResolution:(USPurchaseResolution)resolution
                                       product:(NSString *)product
                                      quantity:(NSUInteger)quantity
                                         price:(float)price
                                      currency:(NSString *)currency;

解决之一

• USPurchaseResolutionBuy如果购买成功
• USPurchaseResolutionCancel如果用户取消了购买
• USPurchaseResolutionFraud如果检测到这是欺诈性购买
• USPurchaseResolutionRefund如果您正在退还购买

产品 - 产品名称，由SKProduct对象的productIdentifier属性提供
数量 - 交易期间购买的产品数量，如SKPayment对象的quantity属性中设置
价格 - 返回的price.floatValue的价格值，其中price是SKProduct对象的价格属性
货币 - 返回的值由[priceLocale objectForKey:NSLocaleCurrencyCode]，其中priceLocale是SKProduct对象的priceLocale

当SDK发送一个与该方法记录的事件的InAppPurchase事件时，它将在交易与App Store的交易中使用收据对象；Upsight服务器使用苹果服务器验证此收据。

如果您有一笔未涉及苹果商店的购买要记录，您可以使用此方法代替

+ (void)recordMonetizationEventWithTotalPrice:(float)totalPrice currency:(NSString *)currency;

总价 - 交易的总金额
货币 - 通常使用[[NSLocale currentLocale] objectForKey:NSLocaleCurrencyCode]检索

推送

推送通过USPush接口支持。推送内容通过Push特定的海报显示，该海报由USPush接口管理。要集成推送，您必须

1. 将USBillboardDelegate协议添加到您的App Delegate并实现presentingViewControllerForBillboard:
2. 通过在您的App Delegate的didFinishLaunchingWithOptions:方法中调用[USPush registerForPushNotifications]进行推送注册。
3. 在您的App Delegate的application:didRegisterUserNotificationSettings:方法中调用USPush API方法didRegisterUserNotificationSettings:。
4. 从didRegisterForRemoteNotificationsWithDeviceToken:调用USPush API方法registerPushToken:。
5. 接收到远程通知时，将USPush横幅的代理设置为您的App Delegate类，并调用USPush接口的handleRemoteNotificationWithUserInfo:方法。
6. 如果您计划在推送通知到达时开始下载内容，这被称为“静默”推送通知，请从目标设置中“后台模式”的列表中检查“远程通知”。

以下是一个正确集成推送的sample AppDelegate实现示例。

@interface AppDelegate () <USBillboardDelegate>
@end

@implementation AppDelegate	

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Upsight setDefaultLogLevel:UpsightLoggerLevelDebug];

    // Override point for customization after application launch.
    [USPush registerForPushNotifications];
    
    return YES;
}

- (void)application:(UIApplication *)application didRegisterUserNotificationSettings:(UIUserNotificationSettings *)notificationSettings
{
    [USPush didRegisterUserNotificationSettings:notificationSettings];
}

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
    [USPush registerPushToken:deviceToken];
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
    [USPush pushBillboard].delegate = self;
    [USPush handleRemoteNotificationWithUserInfo:userInfo];

    if (NULL != completionHandler) {
        completionHandler(UIBackgroundFetchResultNoData);
    }
}

- (void)applicationWillResignActive:(UIApplication *)application {
    // Sent when the application is about to move from active to inactive state. This can occur for certain types of temporary interruptions (such as an incoming phone call or SMS message) or when the user quits the application and it begins the transition to the background state.
    // Use this method to pause ongoing tasks, disable timers, and throttle down OpenGL ES frame rates. Games should use this method to pause the game.
}

- (void)applicationDidEnterBackground:(UIApplication *)application {
    // Use this method to release shared resources, save user data, invalidate timers, and store enough application state information to restore your application to its current state in case it is terminated later.
    // If your application supports background execution, this method is called instead of applicationWillTerminate: when the user quits.
}

- (void)applicationWillEnterForeground:(UIApplication *)application {
    // Called as part of the transition from the background to the inactive state; here you can undo many of the changes made on entering the background.
}

- (void)applicationDidBecomeActive:(UIApplication *)application {
    // Restart any tasks that were paused (or not yet started) while the application was inactive. If the application was previously in the background, optionally refresh the user interface.
}

- (void)applicationWillTerminate:(UIApplication *)application {
    // Called when the application is about to terminate. Save data if appropriate. See also applicationDidEnterBackground:.
}

#pragma mark - Billboard delegate

- (UIViewController *)presentingViewControllerForBillboard:(id<USBillboard>)aBillboard
{
    UIViewController *topController = [UIApplication sharedApplication].keyWindow.rootViewController;
    
    while (topController.presentedViewController) {
        topController = topController.presentedViewController;
    }
    
    return topController;
}

@end

管理变量

此功能允许您在应用程序中使用管理变量；这些是在服务器上设置值的变量。管理变量通过标签引用。

首先，您必须在名为UpsightUXMVariables.plist的文件中声明您的管理变量。

默认字段应包含当该管理变量未被服务器更新时应返回的值。描述字段应包含描述该管理变量用途的string。类型字段定义了管理变量的类型。变量可以是类型string、integer、float或boolean。标签字段定义了您在代码中引用该变量的名称。每个标签必须在您的应用中是唯一的。最大字段仅用于数字类型变量。它定义了管理变量可以返回的最大数值；任何更大的值都将被该值替换。最小字段仅用于数字类型变量。它定义了管理变量可以返回的最小数值；任何更小的值都将被该值替换。

在您想要访问管理变量的源文件中，导入Upsight框架。

#import <UpsightKit/UpsightKit.h>

然后，调用以下对应的USManagedVariable类方法，该类方法与您访问的管理变量的类型相对应。

+ (id<USManagedString>)managedStringWithTag:(NSString *)aTag;
+ (id<USManagedInteger>)managedIntegerWithTag:(NSString *)aTag;
+ (id<USManagedFloat>)managedFloatWithTag:(NSString *)aTag;
+ (id<USManagedBoolean>)managedBooleanWithTag:(NSString *)aTag;

返回的对象将具有适合其类型的value方法。该方法返回从服务器检索的最新值，或者尚未检索到值时的默认值。

id<USManagedString> uxmString = [USManagedVariable managedStringWithTag:@"personage_name"];
NSLog(@"The current value of personage_name is %@", uxmString.stringValue);

如果希望当系统更新管理变量的值时收到通知，您可以将委托设置在变量观察器上。

[Upsight variableObserver].delegate = self;

您分配给变量观察器代理的对象必须符合USManagedVariableObserverDelegate协议。此调用必须在调用您的app委托的applicationDidBecomeActive:方法之前进行。

如果您实现了可选的observer:didSynchronizeManagedVariables:方法，管理变量观察器将在所有管理变量更新完毕后立即调用您的实现。此调用包含包含所有更新变量的标签的NSArray。

如果在调用observer:didSynchronizeManagedVariables:之前保留了访问管理变量的任何引用，则需要在此之后刷新这些引用，以查看新值。

如果您希望防止管理变量的更新，可以覆写 observerShouldSynchronizeManagedVariables: 方法。如果您从该方法返回 NO，则不会更新任何管理变量。该方法在每次会话开始时都会被调用，这样您就有机会接受之前拒绝的更新。

SDK 大小

Upsight SDK 会将您提交给 iTunesConnect 的内容大小增加 450 KB。添加中介 SDK 将使应用程序的大小最多增加 3.1 MB。如果您的应用程序已经链接了一些或所有中介 SDK 所依赖的框架，则影响将减少。

测量是通过从 Xcode 7.2 导出 ipa 文件并使用“准备上传到 App Store”以及比较在 Finder 中的大小进行的。