引言

deltaDNA iOS SDK允许你的原生的iOS游戏发送游戏中的事件和玩家行为信息到deltaDNA。

事件被以JSON对象发送到deltaDNA平台,这些事件被使用在线的显示面板来管理和跟踪。

当你的游戏触发事件以后,这个SDK将在本地存储它们并在网络连接可用时定期上传或者在你选择的时间上传。这允许SDK收集数据而不考虑网络连通性,并让你可以控制上传的时间和频率。

事件的复杂度有所不同,但是都来自同一个事件格式。这个文档和附加的案例应用将提供多种事件案例。

这个SDK的源码采用Objective-C编写,其在GitHub的这里可用。

DeltaDNA iOS SDK 4.1.0版本:

重要的改变:

4.0.0版本是这个SDK的一个重要更新,如果你从一个早期版本的SDK更新,有若干改变需要被重构。V4.1.0版本引入了一些进一步的优化和补充。之前版本的SDK和发行的文档在发行说明页面可用。

导入SDK

为了导入这个SDK到你的项目,你可以使用我们的CocoaPods项目。

首先,你将需要确定你已经安装了pods,这可以用下面的命令来实现:

$ sudo gem install cocoapods

下一步是在你的Xcode项目文件夹中创建一个Podfile,通过这一步来导入到你的项目,并执行如下命令:

$ pod init

这个将创建一个名为Podfile的文件,在这个podfile文件中你可以定义你想要包含在你的项目中的库并引用这些库。要添加这个deltaDNA的SDK需要确保包含了如下内容

现在Podfile知道了什么框架/库你想要添加到你的项目中。要安装它们,你需要在你的项目中运行如下命令:

$ pod install

更多关于CocoaPods的信息请查看https://cocoapods.org。

启用SDK

这个SDK需要在你能够从你的游戏发送事件之前启动。

添加下面的导入声明。

启动参数

你启用这个SDK前,将需要补充至少三个参数。这些参数可以从你的“游戏详情”页面找到。

iOS-environment-variables

  • environmentKey:这是一个分配给你的应用的唯一的32位字符型字符串。你将被为你的游戏开发和产品分配相互独立的应用键值。
  • collectURL:这是收集你的事件的服务器地址。
  • engageURL:这是提供实时A/B测试(real-time A/B Testing)和命中目标(Targetting)的服务器地址。这只在你的游戏使用这些功能时被要求。
  • userID (可选):每个用户需要有一个唯一的userID(用户ID)。如果你的游戏可以提供一个唯一的userID,你可以使用它。另一种选择,如果没有一个用户ID被提供并为后续所有事件使用,这个平台将生成一个唯一的用户ID。要生成一个唯一的用户ID,只要在这个SDK第一次启用时将UserID参数置空

这些参数可以从你的游戏详情页面找到。请注意,你的开发(DEV)和实际(LIVE)环境有不同的environmentKey参数。当你从开发和测试环境迁移到产品时,你将需要改变这个你启用SDK时的环境键值。

这是启用这个iOS SDK和开始发送事件所需的最少代码。SDK第一次运行时其将自动发送newPlayer事件,并且游戏每次运行时自动发送gameStartedclientDevice事件。继续阅读以找到如何实现除了记录少数自动事件,并开始解锁deltaDNA其他事件、参数、自己的自定义事件、A/B测试和有针对性活动的强大功能。

请确保你在你的APP的主线程中运行deltaDNA SDK

事件剖析

所有的事件都以一个共同基础架构的JSON文件记录下来。这个文件对每个事件类型各不相同,但是所有的这些事件文件都遵循如下的最小架构:

iOS SDK将为你发送的每一个事件自动生成userID、sessionID、eventTimestamp、platform和sdkVersion参数。当你添加额外的参数到每一个事件时,其应当被放置于eventParams对象中。

在你的JSON事件中参数的顺序并不重要。

你可以在事件管理器(Event Manager)检查每个事件要求的参数,其类型以及任何格式或者枚举规则。

参数可以是可选的(Optional)或者必需的(Required)。如果你没有为其设置一个有效值,所有可选参数不必须要被包含在你的事件中。最好是将其完全排除,而不是将其的值设置为零或空。

基本的事件结构为记录不同层次复杂性的事件提供了非常强的灵活性,从像上面那个例子一样的非常简单的事件到包含嵌套数组的复杂事件。下面的代码案例将展示从简单到复杂的各种事件。

请注意所有的事件都需要确认,如果他们与事件管理器(Event Manager)中的架构不同,其将被拒绝。

设置

上面展示的简单初始化代码是开始从你的玩家收集分析数据要求的最少代码。你将很快开始添加更多的事件和调整你的实现。确保进一步查看这个页面的下面部分,关于完整的设置、方法和帮助列表。同时,这里有一些在调用开始之前你应当做的有用的事情。

  • 设置你的游戏的 客户端版本(clientVersion。这是明智的,并且可以非常有效的确认在你的游戏不同版本之间玩家的不同行为。SDK设置可以在SDK启用前设置。
  • 你可能需要使用 setSessionTimeoutSeconds方法改变会话超时设置以适配你的游戏。
  • 详细的调试在pod文件中默认启用。
    还有许多其他的有用设置将在后续被介绍。这将帮助你实现自动事件收集、缓存和通信。请确保查看了这些内容。

案例1——一个简单事件。

我们已经看到的开始代码将自动发送newPlayer、clientDevice和gameStarted事件到deltaDNA。下面的代码中我们将添加一个我们自己的事件到代码。

当我们添加我们的游戏到deltaDNA时,7个事件将自动添加。这些事件对于所有的游戏往往是标准事件,被用于驱动显示界面的很多内容。现在我们将只使用其中的一个标准事件。

如下的JSON事件将被上传

案例2——添加一个新的模板事件

前一个案例使用了我们7个标准事件中的一个。这次我们将做一些更进一步的工作。我们将从预设的模板事件列表添加一个事件到我们的框架,添加一个额外的定制化参数然后从我们的代码触发这个事件。

从事件模板列表添加一个missionStarted事件到你的事件框架,然后添加一个新的字符串类型的missionDifficulty参数。

使用事件助手触发missonStarted事件的代码。

如下的JSON事件将被上传

粘贴事件JSON到事件菜单的相互验证可以帮助解决错误,我们的missionStarted事件通过了首次验证。

案例3——一个复杂事件

前面的案例非常简单,并没有太多需要解释的。但是,下面的案例更复杂一些,因为其介绍嵌套、矩阵和一些玩家购买、交易、赢得、与游戏或其他玩家交换货币和装备时可能会遇到的特别对象。好消息是其结构非常的标准,下面的事件可以足够的复杂。

我们将触发一个记录玩家使用一些真实货币购买一个包括一些虚拟货币和装备的宝箱的交易(transaction)事件。我们还将利用deltaDNA与Apple商店的收入确认功能来检查交易是否有效。

正如你看到的交易(transaction)事件的结构有一些复杂。其包括一些用来记录productsSpentproductsReceived的产品(Product)对象。

我们的JSON事件将看起来像

下面的代码被要求来创建它。

上面的交易(Transaction)事件被使用交易(Transaction)助手类创建。还要值得注意的是货币币值总是被以整数为最小货币单位,并且realCurrencyType是一个基于ISO-4217标准的三位货币代码。

上面的代码片段是4.99美元。

 

交易确认

这个平台可以承担在Apple商店的交易收据确认功能,以确保所有显示在你的显示界面的收入都是真实的收入而没有被屏蔽的游戏或者忽略的设备。

如果你想要使用交易确认你将需要添加一些细节到“编辑游戏详情(Edit Game Details)”页面。这个页面可以从欢迎页面左侧的“管理游戏(Manage Games)”链接进入。
例如,对于Apple你将要设置你的9位Apple StoreID,例如971883677和到Apple收据确认服务的链接https://buy.itunes.apple.com/verifyReceipt

你还要和每个交易事件一起发送三个参数来告诉deltaDNA这个交易应该被确认。

例如,确认一个Apple商店的IAP

transactionReceipt是一个从Apple返回的基本64位收据数据。请查阅Apple开发者网站以了解关于Apple收据确认功能的详细信息

这时deltaDNA将确认你的收入,并添加一个额外的revenueValidated参数到你的交易事件,其包括如下潜在的值。

  • 0 – 不进行确认
  • 1 – 收入通过确认检查
  • 2 – 收入未通过确认检查
  • 3 – 收入尝试确认,但结果未知(确认服务可能不可用)

带有状态码2或3的交易确认失败,将被排除在你的收入计算图表和用户指标之外。

在线视频页面有一个关于收入确认的更多细节的在线视频和附属的演讲幻灯片

案例4——吸引(Engage)

游戏可以从吸引(Engage)取回时间敏感信息来决定基于A/B测试结果和活动(Campaigns)是否应当在一个特定的时间对用户产生一个特别的行为。即你的游戏应当在一个游戏中预定的决策点发送吸引(Engage)请求,响应将允许你立刻个性化的制定对玩家的游戏行为。

下面的案例展示了你可以如何使用吸引(Engage)来实现改变一个IAP对玩家做出的行动:

一个目标活动将被在deltaDNA平台为特定目标用户设置并通知这个游戏任何需要被修改的参数或者应当被发布的消息。
这个游戏这时可以:

  1. 发出一个吸引(Engage)请求
  2. 对回调中接收的回应做出反应。

发出吸引(Engage)请求的代码类似于

这将创建一个包括如下JSON文件的吸引(Engage)请求,并将其发送到吸引(Engage)。

吸引(Engage)将非常迅速的处理你的请求,一般10毫秒左右,但是往返的时间将取决于网络因素。因此,你的游戏应当被构造为这种情形,如果用户正在使用潜在的高带宽连接,其不会产生延迟。

吸引(Engage)响应包括一个transactionID和一个包含一些关于玩家在这个时间点参数的参数对象。

如果这个设备在发送吸引(Engage)请求时没有网络连接,那么上次成功发送吸引(Engage)请求时在同一个决策点的缓存响应将被用于执行这次响应。isCachedResponse参数将会用来指明这是一个缓存响应。

你可能收到一个响应包括transactionID但是没有包含个性化值的参数。这表明玩家未能成功达到任何资质标准或者被分配到一个控制组。

如果服务器有一个错误的处理你的吸引(Engage)请求,吸引(Engage)将用如下的错误代码响应。

  • 400 – 输入格式畸形或者其他形式的不正确,或者你发送的实时参数没有被添加到你的游戏参数列表。
  • 403 – 保密的哈希键值不正确或者吸引(Engage)在你的账号没有被启用。
    请检查你已经启用了“按需定制版(On-Demand)”包在你的游戏(Game)->包(Packages)页面,要做这个操作你可能需要在你的deltaDNA账号获得账号所有者权限。
  • 404 – 不正确的链接或者未知的环境键值

图片消息

吸引(Engage)动作也可以实时发送基于图片的消息到你的游戏,并展示弹出的消息。每个动作被设计为活动的一部分,并被发送到一个选择的用户。这个iOS SDK有一个 ImageMessage类用来在你的游戏上一层绘制图片消息。这个弹出是事件驱动的,因此你能够控制何时图片从我们的服务器下载,何时展示给玩家,和获知玩家是否点击其中的按钮或者关闭图片消息的行为。

每个消息由两部分组成,一个智能画面(sprite map)包括背景图片和一些按钮,以及描述如何显示这些部分的布局规划图。这个布局图用来强制约束如何按比例放置弹出的位置。这意味着我们不需要担心屏幕的尺寸,但是我们也可以保护屏幕的一部分不要被覆盖。图片可以在符合这些约束的前提下画的尽可能大,同时仍保持原始的长宽比。

图片消息的吸引(Engage)请求和其他的A/B测试或者活动请求是相同的

吸引(Engage)响应包括来自ImageMessage类的所有信息来渲染你的图片和按钮。每个按钮和背景图片可以有一个能够在响应Delegate被读取的行为。这个行为的类型(Type)可以是无(none)关闭(dismiss)链接(link)动作(action)
如果类型是链接(link)或者动作(action),一个值(Value)字段将在响应Delegate提供一个字符串值。如果是一个链接(link),这时浏览器将被SDK自动打开。

图片消息类

要在你的游戏使用一个图片消息(ImageMessage),你应当首先创建一个吸引(Engagement)对象。

然后,在Engagement对象中创建你的吸引(Engage)请求,并声明响应句柄。

这时你可以从吸引(Engage)响应创建一个ImageMessage对象,并从图片消息获得资源

然后你可以在资源一旦被抓取时使用一个Delegate来显示图片消息

进一步,Delegates可以被用来回应玩家点击按钮或者关闭图片消息。

图片消息还可以被用来与智能广告(SmartAds)针对面向特定玩家的特定奖励视频广告配合使用。使用你的所有由deltaDNA活动工具控制的命中目标和分段决策。

rewardedAdImageMessage

 

Apple推送通知

deltaDNA iOS SDK可以为设备存储Apple推送通知Token,并将其发送到deltaDNA,因此你可以发送推送通知消息给玩家。你的应用将负责从Apple检索(或刷新)推送的Token并将其存储到SDK。谢天谢地,这是非常简单的。

要请求一个推送通知Token,你将需要添加一些代码到你的AppDelegate.m文件,

请求来自Apple的Token。

要处理从Apple返回的Token,并将其发送到deltaDNA

以及处理Apple未能为通知注册这个APP的情形

 

这时Token将在下一次上传事件时被通过一个notificationServices 事件发送到deltaDNA。请注意如果你更新这个推送通知你将需要调用设置PushNotificationToken属性来上传存储的Token。

你还需要上传你的iOS证书给deltaDNA平台,以让Apple接受从deltaDNA发送的推送通知请求。你可以在显示面板的SETUP(设置)->TOOLS(工具)-NOTIFICATIONS(通知)->Manage Identity(管理ID)部分做这些。你的来自Apple的证书将需要包括你的存成一个.p12文件的证书和密钥。CertificateIcon

关于如何为你的应用准备接收推送通知信息(Push Notification Messages)、创建一个证书和用正确的格式保存证书的更多信息,请查看我们的Apple证书指导

记录推送通知事件

当你的APP接收到一个推送通知你可以回复一个事件到deltaDNA,因此你可以将其包括在你的分析中并跟踪开放率。 recordPushNotification方法可以在如下时候被调用:

这个APP直接从推送通知运行时。

或者当APP已经运行时。

注意:在SDK已经启用前调用 recordPushNotification方法是安全的。

推送通知深度耦合

简单的推送通知消息只被用作提示玩家打开你的APP,然而你可以通过在你的APP可以响应的通知有效载荷传递信息创建更多的复杂行为。这经常被用于如果玩家打开这个APP时赠予玩家游戏内的资源,或者引导其到达游戏内的一个特殊页面。

为了在iOS实现深度耦合你需要:

  1. 在你的通知有效载荷为APP发送参数以得到响应。
  2. 在你的APP创建连接以响应在通知有效载荷接收的参数
  3. 记录一个事件来跟踪通知的打开率

下面的例子赠予玩家能量升级来作为打开这个APP的奖励。

1)添加键值参数到通知的有效载荷

当你在通知管理器创建一个新的通知时有效载荷参数被添加到iOS页面的按钮。吸引(ENGAGE)->通知(NOTIFICATIONS)->创建通知(CREATE A NOTIFICATION)

parameters2

可以添加你想要的任意多的键/值对到通知有效载荷,但是全部的推送通知消息不能超标2048字节。

notification

2)在APP中响应有效载荷参数。

你将需要在“Application Delegate”文件添加一些代码到 application:didFinishLaunchingWithOptions方法以从 launchOptions获取参数

如果这个APP从推送通知运行

如果当通知接收到时这个APP已经运行。

3)记录一个事件来跟踪通知打开率

推送通知传送不能被Apple保证,他们描述其为“尽力而为”,因此你将需要跟踪哪些玩家打开了他们。因此当这个APP被一个通知打开时你应当记录一个事件。你还可以在事件中传回一些参数,将让你识别准确的通知和一些其他被使用的有效载荷参数。

你可以为其使用任何事件,我们为这个案例创建了一个notificationOpened事件,并将通知消息和有效负载参数添加进去,从而我们可以跟踪其效果。这个事件还可以被用于创建玩家分段以为接下来的通知重新命中目标玩家。

因此,我们的APP运行代码可能被扩展一些,看起来像:

这将导致如下的事件被记录下来。

Apple ID

如果你想从一个设备记录Apple供应商ID(VendorID)或者广告ID参数,你将负责从设备检索他们并在一些你想要将它们添加到的事件中以自定义参数将其发送。你还将需要在事件管理工具中添加这些自定义参数。

注意:从2014年2月起Apple拒绝应用在不显示广告的情况下收集广告ID参数。

附录1——类参考

DDNASDK(deltaDNA SDK)

属性

  • settings(设置)
    设置对象让你修改默认的SDK设置。请查看下面的设置参考以了解更多信息。
  • hashSecret(哈希密码)
    哈希密码属性应当被设置,如果你想要你的APP在验证你的事件时使用哈希。
  • clientVersion(客户端版本)
    这个属性应当由你的APP设置,以便区分使用不同版本游戏的玩家。如果你没有填写这个属性,SDK将记录一条警告消息。
  • pushNotificationToken(推送通知Token)
    如果你打算从deltaDNA平台发送推送通知消息到设备,这个属性应当在启用SDK前设置。一旦设置,pushNotificationToken将随着每条gameStarted事件被传递到deltaDNA。你的APP将负责从Apple请求一个推送通知Token。
  • environmentKey(环境键值)
    这个只读属性返回正在使用的SDK与deltaDNA通信的环境键值。你有两个环境键值,一个开发键值和一个实际键值。这些键值被用作保存你的开发和测试数据,并与你的真实产品数据相分离。这个属性应当被提供给SDK,在SDK启用方法中作为一个参数。
  • collectURL(收集链接)
    这个只读属性返回正在使用的SDK发送事件到deltaDNA的链接。这个属性应当被提供给SDK,在SDK启用方法中作为一个参数。
  • engageURL(吸引链接)
    这个只读属性返回正在使用的SDK进行吸引(Engage)命中目标和A/B测试请求时的链接。这个属性应当被提供给SDK,在SDK启用方法中作为一个参数。
  • userID(用户ID)
    这个只读属性可以被用于从SDK检索用户ID。这个用户ID要么由SDK自动生成,要么在SDK启用时由客户端APP提供。
  • sessionID(会话ID)
    这个只读属性返回SDK正在使用的会话ID。这个SDK每次启用时会生成一个新的会话ID。
  • platform(平台)
    这个只读属性返回游戏正在播放的平台。这是由SDK自动添加的。
  • isInitialised(初始化)
    这个只读属性返回一个布尔值指示这个SDK是否已经被初始化。

方法

  • start(启用)
    启用deltaDNA SDK。要求三个可以从deltaDNA面板你的游戏详情页面找到的强制参数(environmentID,collectURL,engageURL),请查看下面的图片。第四个可选的userID参数如果你提供了将被使用。如果你没有提供userID,这个SDK将为你生成一个唯一的随机userID,并在随后所有的事件中使用它。
    你需要在启用方法中提供的这个参数可以从delta面板你的游戏详情页面找到。
  • stop(停止)
    发送一个gameEnded事件并禁用后台上传事件。
  • newSession(新会话)
    为当前用户改变会话ID(sessionID)。如果你的APP在较长一段时间后从后台重新使用时这将非常有用。
  • recordEvent(记录事件)
    记录事件方法创建一个JSON事件并将其存储在设备本地。SDK将定期或者在上传方法被调用时上传所有存储的事件。recordEvent方法要求你提供事件名称(eventName)和你可以选择提供的其他参数。你的游戏支持的每个事件的时间架构可以在deltaDNA的事件管理工具被查看并编辑。你的事件被严密的确认以防止任何错误损坏你的产品数据,你应当为每个事件使用这个架构,并在检测你的游戏时使用QA工具。你记录的每个事件将包括一组参数。一个事件只是一个JSON对象,你可以将这些参数附到一个事件作为一个NS字典(NSDictionary)或者你可以使用一个deltaDNA事件构建助手对象。每个对象都有一个上层的触发事件(triggerEvent)方法。
  • upload(上传)
    SDK将每隔1分钟定期自动上传本地存储的所有事件。如果你想要覆盖这个行为,你可以使用上传方法来在你选择的时间发送事件。如果你的APP消耗资源非常巨大并且你想要在运行平稳时发送事件,你可能想要这么做。
  • clearPersistentData(清除持续数据)
    清除所有本地存储的数据包括userID,pushNotificationToken,clientVersion和任何还没有被从客户端上传的事件。
    [sdk clearPersistentData ];
  • recordPushNotification(记录推送通知)
    发送一个notificationOpened事件到deltaDNA,从而通知打开率可以被记录和分析。如果这个通知被用来打开这个APP时didLaunch标志应当被设置为真(True),如果这个APP已经运行应被设为假(False)
     

DDNASettings(deltaDNA设置)

设置对象可以被用来修改设置,以自动控制SDK的特征和通信。

  • onFirstRunSendNewPlayerEvent(第一次运行发送新玩家事件)
    这个SDK第一次运行时将自动发送一个新玩家(newPlayer)事件。默认为真(True)。如果你想要覆盖这个行为并用额外参数触发你自己的新玩家(newPlayer)事件,将其设置为假(False)。
  • onStartSendClientDeviceEvent(启用发送客户端设备事件)
    这个SDK将在你的APP每次运行时自动发送一个客户端设备(clientDevice)事件。clientDevice事件中的这个参数由SDK自动填充。默认为真(True)。如果你想要覆盖这个行为并用额外的参数触发你自己的客户端设备(clientDevice)事件,将其设置为假(False)。
  • onStartSendGameStartedEvent(启用发送游戏启用事件)
    这个SDK将在APP每次运行时自动发送一个游戏启用(gameStarted)事件。默认为真(True)。如果你想要覆盖这个行为并用额外的参数触发你自己的游戏启用(gameStarted)事件,将其设置为假(False)。
  • httpRequestRetryDelaySeconds(http请求重试间隔秒数)
    SDK应当在每次失败的上传尝试之间等待的秒数。默认是2秒。
  • httpRequestMaxTries(http请求最大次数)
    失败的上传尝试后应当尝试的最大重试次数。默认是5次。
  • httpRequestTimeoutSeconds(http请求超时秒数)
    SDK在一次上传请求超时前应当等待的描述。默认是20秒。
  • backgroundEventUpload(后台事件上传)
    如果这个属性设置为真(True),SDK将定期自动上传事件。默认为真(True)。如果你想要自己控制上传请求的时机,将这个属性设置为假(False)。如果你的游戏消耗资源特别大,并且你想要限制你的上传在游戏并不挑剔时间的阶段,例如游戏开始、菜单页面或者会话被完成后,你可能想要这么做。如果你自己控制上传,请注意在当前会话任何未被上传的事件将会在你调用上传方法时在下一个游戏会话中上传。然而,如果玩家长时间未玩这个游戏,这个事件将会过时,此时其被上传,但结果将是被事件验证器拒绝。
  • backgroundEventUploadStartDelaySeconds(后台事件上传启用延迟秒数)
    SDK启用后直到其尝试上传事件的延迟秒数。默认为0秒以确保任何前一会话存储的事件都被立刻上传。
  • backgroundEventUploadRepeatRateSeconds(后台事件上传重复率秒数)
    自动事件上传尝试之间的秒数。

DDNAEvent(deltaDNA事件)

事件对象帮助你创建结构化的事件。

  • eventWithName(带有名称的事件)
    初始化一个带有特定名称的事件对象。
  • setParam(设置参数)
    为事件对象添加一个参数
  • dictionary(字典)
    返回一个事件对象的NS字典(NSDictionary)。

DDNAProduct(deltaDNA产品)

产品对象提供给你方法来帮助你创建产品对象,用于包含奖励的交易(Transactions)和事件。

  • init(初始化)
    初始化产品构造器对象
  • dictionary(字典)
    返回一个产品的NS字典(NSDictionary)的对应表达。
  • setRealCurrency(设置真实货币)
    添加一个真实货币对象到产品
    注意:一个产品构造器只能包括一个真实货币对象。真实货币类型(RealCurrencyType)应当是一个ISO-4217标准的3位货币代码。货币数量应当是一个最小货币单位的整数型。因此下面的代码片段等同于4.99美元
  • addVirtualCurrency(添加虚拟货币)
    添加一个虚拟货币项到产品构造器。你可以添加多个虚拟货币到一个产品构造器,它们可以被放置在一个虚拟货币(VirtualCurrencies)数组中。
  • addItem(添加项目)
    添加一个项目到产品构造器。你可以添加多个项目到产品构造器,他们将被放置在一个项目(Items)数组中。