ColorTV tvOS SDK

入门指南

在开始之前，请确保您有以下内容：

• 在Color仪表板的“我的应用”部分中添加了您的应用程序。您需要这样做才能获取您的App ID，您将使用我们的SDK将其添加到您的应用程序中。

• 我们的最新tvOS SDK支持最新的Xcode（7.2）。请确保您正在使用Xcode（7.2）或更高版本，以确保顺利集成。

添加tvOS SDK

连接您的应用程序

有两种方式可以将Color添加到您的Xcode项目中

2. 手动集成

在此处下载tvOS SDK

下载和解压SDK

解压并打开文件夹，然后转到ColorTV框架文件夹。包括模拟器和实际设备的框架。对于生产，请使用tvos-device文件夹中的框架，**仅**使用模拟器中的框架进行测试。

在Xcode的左上角点击您的应用程序，然后转到项目设置。选择“常规”并选择适当的目标，在大多数情况下，它对应于项目名称。然后拖动并放置COLORAdFramework.framework目录到“嵌入式二进制文件”部分。

完成后，您将看到COLORAdFramework在“嵌入式二进制文件和链接框架和库”部分中。请注意，框架将自动添加到“链接框架和库”。如果您首先将其添加到“链接框架和库”，它将**不会**自动添加到两者中。

添加自定义JS类（仅TVML）

打开AppDelegate.m，并添加函数appController:evaluateAppJavaScriptInContext。如果函数已经存在，请将以下代码添加到函数体中。

-(void)appController:(TVApplicationController *)appController evaluateAppJavaScriptInContext:(JSContext *)jsContext {
    [jsContext.globalObject setObject:[COLORAdController class] forKeyedSubscript:@"COLORAdController"];
    [jsContext.globalObject setObject:[COLORUserProfile class] forKeyedSubscript:@"COLORUserProfile"];
}

提交到AppStore

在提交您的应用程序到iTunesConnect之前，请确保使用了正确的COLORAdFramework版本。提醒一下。我们提供两个二进制文件——适用于arm64和i86架构的通用文件以及仅适用于arm64的文件（目录：tvos-device）。记住，只有第二个文件能通过iTunesConnect验证。

初始化SDK

打开AppDelegate.m，并修改由仪表板生成的App ID对应的函数application:DidFinishLaunchingWithOptions:的主体。

[[COLORAdController sharedAdController] startWithAppIdentifier:@"YOUR_APP_ID_HERE"];

COLORAdController.sharedAdController().startWithAppIdentifier("YOUR_APP_ID_HERE");

COLORAdController.sharedAdController().startWithAppIdentifier("YOUR_APP_ID_HERE");

记得导入COLORAdFramework模块。在类实现上方添加以下代码行（如果使用TVML/TVJS，则将导入声明添加到AppDelegate.m中）。

@import COLORAdFramework;

@import COLORAdFramework

请注意，在运行iOS时模块名称为COLORMobileAdFramework。

展示广告

ColorTV提供了许多不同类型的广告，这些广告会由我们服务器自动提供以吸引您的观众。您不需要关心适当的广告和其内容，我们已经为所有用户优化了最佳性能内容。您需要做的只是添加几行代码，广告就将将在您想要的位置和任何您想要的时间显示。此功能在iOS上不可用。

[[COLORAdController sharedAdController] adViewControllerForPlacement:COLORAdFrameworkPlacementAppLaunch withCompletion:^(COLORAdViewController * _Nullable vc, NSError * _Nullable error) {
        if(vc) {

            vc.adCompleted = ^(BOOL videoWatched) {
                dispatch_async(dispatch_get_main_queue(), ^{
                    [self dismissViewControllerAnimated:YES completion:nil];
                });
            };

            dispatch_async(dispatch_get_main_queue(), ^{
                [self presentViewController:vc animated:YES completion:^{

                }];
            });
        } else {
            NSLog(@"Error: %@", error);
        }
    } expirationHandler:^(COLORAdViewController * _Nullable expiredVC){
        //If you kept a reference to COLORAdViewController but haven't shown it yet, you should discard it now
    }];

        COLORAdController.sharedAdController().adViewControllerForPlacement(placement, withCompletion:{ (vc , error) in
            guard let vc = vc else {
                print("Failed to initialize ad view controller, error: \(error?.description)")
                return
            }

            vc.adCompleted = { (videoWatched) in
                self.dismissViewControllerAnimated(true, completion: nil)
            }

            dispatch_async(dispatch_get_main_queue()) {
                self.presentViewController(vc, animated: true, completion: nil)
            }
        }, expirationHandler: { (expiredVc) in
            //If you kept a reference to COLORAdViewController but haven't shown it yet, you should discard it now
        })

COLORAdController.sharedAdController().prepareAdForPlacementWithCompletionAndExpirationHandler("MainMenu", function(success) {
        if(success) {
            console.log("AD prepared");
            COLORAdController.sharedAdController().showLastAdWithCompletionHandler(function(watched) {
                    console.log("AD closed " + watched);
            });
        } else {
            console.log("AD NOT prepared");
        }
    }, function() {
        console.log("AD expired");
    }
);

我们了解用户体验对于您的应用程序性能的重要性。没有人愿意等待几秒才看到一个广告，无论其内容有多相关，因此我们开发了方法adViewControllerWithCompletion以实现最佳性能。当您认为广告很可能显示时调用adViewControllerWithCompletion。我们强烈建议在所有潜在的将显示广告的地方调用此方法。通过这样做，您可以通过我们的仪表板停止或开始显示应用特定位置的广告，而无需推送更新给用户！

当广告的部分元素加载完成时，会调用完成块。它提供两个参数，viewController和error。框架生成viewController，它将以匹配您应用程序结构的方式显示。大多数情况下模态视图控制器是可行的，但有时导航视图控制器或某种嵌入视图控制器会更好。这取决于您。

当广告不应再显示时，您将得到通知，并需要定义完成块。在上面的示例中，控制器将从屏幕上简单退场。

您可以保留对viewController的引用并在以后显示它。然而，广告仅在一段时期内有效（大约5-15分钟）。当它失效时，会调用expirationHandler，因此您可以丢弃对viewController的引用。

请注意，大多数操作都是在后台线程上执行的，而与用户界面的交互仅在上主线程上进行。记得在与其他界面交互时使用[NSThread mainThread]（旧样式）或GCD的主要队列（新样式）。

广告位置

在显示广告时，您必须提供您在应用程序中显示广告的上下文。这将使我们能够更有效地定位广告，并为您提供在仪表板中控制显示广告的能力。

[[COLORAdController sharedAdController] setCurrentPlacement:COLORAdFrameworkPlacementStageOpen];

COLORAdController.sharedAdController().currentPlacement = COLORAdFrameworkPlacementMainMenu

COLORAdController.sharedAdController().setCurrentPlacement("StageOpen");

预定义的常量可用，其名称以COLORAdFrameworkPlacement...开头。

显示内容推荐

推荐内容显示类似于展示广告。它可以在您的应用内部任何位置显示，但需要包含一个Position参数来指定具体位置。与广告类似，您可以用多种方式显示内容推荐视图控制器：例如，将其作为模态视图控制器显示，将其推送到导航控制器，等等。

[[COLORAdController sharedAdController] contentRecommendationControllerForPlacement:COLORAdFrameworkPlacementVideoEnd
    andVideoId:@"570d799457dde161ef006cbc" 
    withCompletion:^(COLORRecommendationViewController *vc, NSError *error) {
        if(!vc) {
            NSLog(@"Failed to get recommendation view controller for placement %@, error %@", COLORAdFrameworkPlacementMainMenu, error);
            return;
        }
        vc.contentRecommendationClosed = ^{
            [self dismissViewControllerAnimated:YES completion:nil];
        };

        vc.itemSelected = ^(NSString *videoId, NSURL *videoURL, NSDictionary *params) {
            //play the selected video
        };
        dispatch_async(dispatch_get_main_queue(), ^{
            [self presentViewController:vc animated:YES completion:nil];
        });
    }];

COLORAdController.sharedAdController().contentRecommendationController(forPlacement: COLORAdFrameworkPlacementBetweenLevels, andVideoId: nil) { (vc, error) in
    guard let vc = vc else {
        print("Failed to get content recommendation, error: \((error as? NSError)?.description)")
        return
    }

    vc.contentRecommendationClosed = {
        self.dismiss(animated: true, completion: nil)
    }

    vc.itemSelected = { videoId, videoURL, params in
        //play selected video
        print("Selected item: id \(videoId), url \(videoURL)")
    }

    DispatchQueue.main.async {
        self.present(vc, animated: true, completion: nil)
    }
}

要为特定位置加载数据推荐内容，您需要调用contentRecommendationControllerForPlacement:andVideoId:withCompletion方法。您可以使用预定义的位置之一，例如COLORAdFrameworkPlacementVideoFinished。如果您在播放视频后显示内容推荐，您可以通过videoId参数传递其标识符以获取更准确的推荐。

当用户选择推荐的视频之一时，您将通过itemSelected处理程序得到通知，所以您可以播放此视频。

在使用户关闭内容推荐视图控制器后，将调用contentRecommendationClosed代码块，您需要关闭推荐视图控制器或将其从导航堆栈中删除。

视频事件报告

为了获得更好的内容推荐，您可以使用我们的SDK收集用户在您应用的视频中的行为数据。例如，您可以报告用户在观看25秒后停止了视频。只需调用此trackEventForPartnerVideoId:eventType:secondsWatched方法即可

[[COLORAdController sharedAdController] trackEventForPartnerVideoId:@"570d799457dde161ef006cbc" eventType:COLORAdFrameworkVideoEventStopped secondsWatched:25];

COLORAdController.sharedAdController().trackEvent(.stopped, forPartnerVideoId: "570d799457dde161ef006cbc", andSecondsWatched: 25)

可以报告的事件类型由COLORAdFrameworkVideoEventType枚举定义。

用户资料

另一种为我们提供有助于向您受众提供适当广告的有价值信息的方法是用户资料。您可以通过设置COLORUserProfile单例的属性来提供表征特定用户的基本信息。如果因为某些原因您认为您的应用程序的用户已更改，例如账户已切换，可以调用-(void)reset方法并设置新值。属性age是无符号整数，它表示自用户出生以来经过的年数。如果您不知道确切的值，但能够预测量年龄范围，则将预测范围中间的数字传递。属性gender是字符串字面量，应包含male或female。此外，可以添加一组关键字，以便我们更多地了解您的应用程序的用户。您可以通过调用方法-(void)addKeyword:(NSString*)keyword和-(void)removeKeyword:(NSString*)keyword来操纵关键字。如果要重置配置文件，则关键字集合变为空。

COLORUserProfile *profile = [COLORUserProfile sharedProfile];

[profile reset]; //reset current profile if user is switched in your application.

profile.age = 30;
profile.gender = @"female"; //male or female are expected here

//keywords which may characterize your audience. They are used to target ads more effectively.
[profile addKeyword:@"aviation"];
[profile addKeyword:@"airplane"];
[profile addKeyword:@"airport"];

    let profile = COLORUserProfile.sharedProfile()
    profile.reset() //reset current profile if user is switched in your application.

    profile.age = 30
    profile.gender = "female" //male or female are expected here

    //keywords which may characterize your audience. They are used to target ads more effectively.
    profile.addKeyword("aviation")
    profile.addKeyword("airplane")
    profile.addKeyword("airport")

var userProfile = COLORAdController.sharedAdController().userProfile();

userProfile.reset(); //reset current profile if user is switched in your application.

userProfile.setAge(30);
userProfile.setGender("female"); //male or female are expected here

//keywords which may characterize your audience. They are used to target ads more effectively.
userProfile.addKeyword("aviation");
userProfile.addKeyword("airplane");
userProfile.addKeyword("airport");

赚取虚拟货币

在您的广告中整合虚拟货币将大大增加用户交互以及您的应用程序的货币化。我们提供了一种机制，使用您的应用程序的虚拟货币为用户提供各种激励。必须首先在您的应用程序仪表板中设置虚拟货币，然后添加几行代码才能完全设置。

广告转换由我们的服务器监控，当分配某些货币时，您将得到通知。您可以选择通过NSNotificationCenter获取通知还是使用代理模式。

NSNotificationCenter

[[NSNotificationCenter defaultCenter] addObserverForName:COLORAdFrameworkNotificationDidGetCurrency object:nil queue:nil usingBlock:^(NSNotification * _Nonnull note) {
    NSLog(@"userInfo: %@", note);
}];

NSNotificationCenter.defaultCenter().addObserverForName(COLORAdFrameworkNotificationDidGetCurrency, object: nil, queue: nil) { note in
    print("userInfo: \(note.userInfo)")
}

每次注册转换时（通常当应用程序返回前台时），每个转换都会触发一个通知。请注意，这是一个 Notifications 类的对象，它包含类 NSDictionary 的 userInfo 属性。它包含一些有用的信息，例如分配的货币量或货币名称。

代理人

如果您想使用代理人，请记住将所需类设置为符合COLORAdControllerDelegate协议。然后设置代理。

[COLORAdController sharedAdController].delegate = self;

COLORAdController.sharedAdController().delegate = self

每当注册了转换时，应调用以下方法。详细信息包含与userInfo相同的信息。

#pragma mark - COLORAdControllerDelegate

-(void)didGetCurrency:(NSDictionary *)details {
    NSLog(@"didGetcurrency delegate method: %@", details);
}

func didGetCurrency(details: [NSObject : AnyObject]!) {
    print("didGetCurrency delegate method: \(details)")
}

服务器响应

服务器返回一个键值编码的字典，描述分配的货币。

{
    "currencyAmount": 20,
    "currencyType": "Gold Coins",
    "placement": "AppResume",
    "status": true,
    "timestamp": "2016-08-26T13:02:38.004Z"
}

货币金额是一个无符号整数。它表示分配的货币数量。货币类型是一个字符串。它返回通过服务器开发者仪表板定义的货币名称。位置 - 描述了注册的转换显示的广告的位置。状态 - 定义操作成功。时间戳 - 日期和时间标识符（ISO-8601标准），描述转换在服务器上注册的时间。

货币处理器（JavaScript）

COLORAdController.sharedAdController().currencyHandler = function(details) {
    console.log("::>> currency handler ::<<");
    console.log("::>> currency type: " + details.currencyType);
    console.log("::>> currency amount: " + details.currencyAmount);
    console.log("::>> placement: " + details.placement);
    console.log("::>> status: " + details.status);
    console.log("::>> timestamp: " + details.timestamp);
};