SwiftyiRate中文说明

SwiftyiRate Github

SwiftyiRate Swift语言实现的app内评分，简单易用。

1. Requirements
2. Integration
3. Usage
   
   • Initialization
4. Configuration
5. Advanced properties
6. Methods
7. Delegate methods
8. Localisation
9. Example Projects
10. Advanced Example
11. Release Notes

Requirements

• iOS 7.0+
• Xcode 7

Integration

CocoaPods (iOS 8+)

你可以使用 Cocoapods 来安装 SwiftyiRate，添加pod

pod 'SwiftyiRate'

Podfile:

platform :ios, '8.0'
use_frameworks!

target 'MyApp' do
    pod 'SwiftyiRate', :git => 'https://github.com/PlayApple/SwiftyiRate.git'
end

Usage

Initialization

Add code in AppDelegate.swift

import SwiftyiRate

override class func initialize () {
    //configure iRate
    SwiftyiRate.sharedSwiftyiRate.daysUntilPrompt = 5
    SwiftyiRate.sharedSwiftyiRate.usesUntilPrompt = 15
}

Configuration

---

SwiftyiRate类里面所有可配置的参数和接口全部列举在下面：

var appStoreID: Int?

这个必须匹配你的app apple id（ iTunes Connect后台中app详情下可以看到），通常情况下你无需自己设置该id，SwiftyiRate会通过网络自动从app store获取app具体数据。无网络或者app未上架则无法获取。（此时可以通过设置为其他已经上线的app id用于测试）

var appStoreGenreID: Int?

app类型id，用于区分app为应用还是游戏类型，从而显示不同的rate信息提示框。自动从app store获取app具体数据，无需自己设置。

var appStoreCountry: Int?

两个字母的设备国家码，用于本地化语言，默认读取手机所在地区。如果你想永远出现固定国家语言，则可以修改你想要的国家代码。

var applicationName: String

app名称，默认读取自info.plist。你可以自定义为其他名称。

var applicationBundleID: String?

app的bundle ID，用于获取appStoreID和appStoreGenreID，默认读取自info.plist。无需自行修改。（除非你是测试情况下）。

var daysUntilPrompt: Float

至少使用天数，距离用户首次启动app超过该天数，才会提示用户评分。支持小数，0.5表示12小时。默认值：10。

var usesUntilPrompt: Int

至少使用（启动）次数，防止长时间未使用app，启动app后就出现评分情况。至少使用天数和至少使用（启动）次数同时满足才会提示用户评分。默认值10次。

var eventsUntilPrompt: Int

可提示事件次数，应用或者游戏在某一个使用场景下适合提示用户评分的话，你可以记录一次事件，类似usesUntilPrompt，至少使用天数和可提示事件次数同时满足才会提示用户评分。默认值10次。

var usesPerWeekForPrompt: Float

平均每次使用app次数，注意SwiftyiRate会计算app总使用次数除以距离安装的时间来计算每周使用平均值，只有超过这个值，才会允许评分，长时间不使用app，可能计算出来的平均每周次数为0。默认值0。

var remindPeriod: Float

下一次提示玩家的周期天数，玩家选择稍后提醒后，下一次提示的间隔天数。默认值1天。

var messageTitle: String

评分对话框的标题，如果你不想出现标题，可以设置为空字符串。

var message: String

评分对话框的文本信息，注意不要设置特别长（体验不好）。如果你不想出现文本信息，可以设置为空字符串。

var updateMessage: String  

该文本信息用于新版本中已经在旧版本中评分过的用户，默认值用的message的值。

var cancelButtonLabel: String

评分对话框中取消评分按钮标题

var rateButtonLabel: String

评分对话框中前往评分按钮标题

var remindButtonLabel: String

评分对话框中稍后提示按钮标题，设置为空字符串则不出现该按钮。

var useAllAvailableLanguages: Bool

支持本地化语言，不管你是否已经本地化了app，SwiftyiRate默认会使用SwiftyiRate.bundle下语言包，

如果你希望使用自己的本地化文件，请设置为false。默认值为true（所使用的本地化key下面有介绍）

var promptForNewVersionIfUserRated: Bool

每个新版本都提示用户评分，由于app store会清空新版的评分，所以默认下SwiftyiRate每个版本都会提示用户评分，直到用户选择了拒绝评分。默认值false

var onlyPromptIfLatestVersion: Bool

仅在最新版本中提示用户评分，默认为true。设置为false的话，如果用户未使用最新版本，也会提示用户评分。

var onlyPromptIfMainWindowIsAvailable: Bool

mac app的提示框设置，该功能开发中…

var promptAtLaunch: Bool

是否启动app就提示用户评分（满足条件下），如果你设置为false，启动app时候不会弹出评分框，但是评分条件会继续执行并跟踪。你可以使用该选择自定义一些自己的评分框弹出时机和方式。默认值：true

var verboseLogging: Bool

是否打印log到Xcode控制台，默认false。release版注意设置为false。

var previewMode: Bool

预览模式，如果设置为true，在promptAtLaunch=true情况下会忽略弹出条件，直接弹出用户评分框，你可以用于测试。release版本注意设置为false，默认值false。

Advanced properties

---

如果SwiftyiRate默认规则和UI不满足你的要求，你可以通过下面的delegate协议和内部状态实现自定义。

var ratingsURL: NSURL?

app的评分网址，自动获取。

var firstUsed: NSDate?

app首次启动时间，用于daysUntilPrompt规则。

var lastReminded: NSDate?

最近一次提示用户评分的时候，用于再次提示用户。

var usesCount: Int

app启动次数

var eventCount: Int

已经记录了可触发评分事件的次数

var usesPerWeek: Float

用户平均每周使用次数

var declinedThisVersion: Bool

用户点击了取消（拒绝）评分按钮，SwiftyiRate不使用该属性，如果你自定义逻辑，可能会需要。

var declinedAnyVersion: Bool

是否拒绝任何版本的评分，如果你设置为true，SwiftyiRate将永远不会主动提示用户评分。默认false

var ratedThisVersion: Bool

标记用户是否已经评论了该版本

var ratedAnyVersion: Bool

标记用户是否评分了任何版本

weak var delegate: SwiftyiRateDelegate?

代理协议，如果你使用SwiftyiRate帮你管理评分，你无需设置。如果你希望自定义，可以实现该代理协议。后面文档会介绍。

Methods

---

除了上面的一些属性，SwiftyiRate还有下面一些方法

func logEvent(deferPrompt: Bool)

记录可评分事件次数，你可以在app中调用该方法，用于记录可评分事件次数，deferPrompt为true在满足条件情况下，下次启动app时弹出评分。deferPrompt为false则满足条件就立刻弹出提示。

func shouldPromptForRating() -> Bool

是否满足评分条件，如果执行了该方法则将不会执行iRateShouldPromptForRating delegate

func promptForRating()

该方法将立即显示评级提示框没有检查，如果App Store可访问并且没有调用SwiftyiRateShouldPromptForRating，如果你想修改调用该方法的时机，你可以修改其他相关属性或者直接修改promptIfNetworkAvailable 方法

func promptIfNetworkAvailable()

该方法用于检测app在app store是否有效，SwiftyiRateShouldPromptForRating协议方法会先被调用，所以你可以拦截该检测。如果app未上架，你需要手工设置appStoreID 否则该检测会失败。

func promptIfAllCriteriaMet()

如果所有条件都满足，则会弹出评分。SwiftyiRateShouldPromptForRating会先执行，你也可以拦截。

func openRatingsPageInAppStore()

用户正在打开评分网址，会先执行iRateShouldOpenAppStore 函数，如果你实现了该协议且返回false，则不会打开网址，此时你需要自己打开网址。如果打开成功会执行iRateDidOpenAppStore，打开失败会执行 iRateCouldNotConnectToAppStore

Delegate methods

---

的SwiftyiRateDelegate协议提供了下面的方法，可用于拦截SwiftyiRate事件和重写默认行为。所有的方法都是可选的。

optional func iRateCouldNotConnectToAppStore(error: NSError)

SwiftyiRate无法连接到app store，导致原因可能是无网络、app id不正确。

optional func iRateDidDetectAppUpdate()

SwiftyiRate检测到对比上一次启动时间，本次启动的app已经被更新。

optional func iRateShouldPromptForRating() -> Bool

已经满足条件，是否提示用户评分，返回ture则显示提示框。你可以通过该方法，拦截默认提示框，实现自定义提示逻辑。

optional func iRateDidPromptForRating()

已经显示了评分提示框，你可以在此方法中记录评分数据，用于数据统计分析用户评分比例。

optional func iRateUserDidAttemptToRateApp()

用户点击了前往评分按钮。该方法仅在SwiftyiRate默认行为下被调用。如果你自定义了逻辑或者使用了openRatingsPageInAppStore拦截，该协议方法不会被执行。

optional func iRateUserDidDeclineToRateApp()

用户点击了取消（拒绝）评分按钮，该方法仅在SwiftyiRate默认行为下被调用。你可以在此方法中记录评分数据，用于数据统计分析用户评分比例。

optional func iRateUserDidRequestReminderToRateApp()

用户点击了稍后评分按钮，该方法仅在SwiftyiRate默认行为下被调用。你可以在此方法中记录评分数据，用于数据统计分析用户评分比例。

optional func iRateShouldOpenAppStore() -> Bool  

SwiftyiRate将要尝试打开app store，你可以返回false用户拦截该行为。从而实现自定义逻辑。

optional func SwiftyiRateDidOpenAppStore()

SwiftyiRate已经打开了App Store评分网址

Localisation

---

SwiftyiRate默认使用SwiftyiRate.bundle来实现字符串本地化为多种语言。

下面是SwiftyiRate 字符串 key：

private static let SwiftyiRateMessageTitleKey = "iRateMessageTitle"
private static let SwiftyiRateAppMessageKey = "iRateAppMessage"
private static let SwiftyiRateGameMessageKey = "iRateGameMessage"
private static let SwiftyiRateUpdateMessageKey = "iRateUpdateMessage"
private static let SwiftyiRateCancelButtonKey = "iRateCancelButton"
private static let SwiftyiRateRemindButtonKey = "iRateRemindButton"
private static let SwiftyiRateRateButtonKey = "iRateRateButton"

如果你希望SwiftyiRate使用自己的本地化文件，你可以设置useAllAvailableLanguages 为false，然后添加上面的key到自己的本地化文件。

请不要直接修改SwiftyiRate.bundle，防止更新SwiftyiRate的时候出现数据丢失。

当然你可以直接修改SwiftyiRate所有字符串内容。

override class func initialize () {
    // overriding the default SwiftyiRate strings
    SwiftyiRate.sharedSwiftyiRate.messageTitle = NSLocalizedString("kMessageTitle", comment: "iRate message title")
    SwiftyiRate.sharedSwiftyiRate.message = NSLocalizedString("kMessage", comment: "iRate message")
    SwiftyiRate.sharedSwiftyiRate.cancelButtonLabel = NSLocalizedString("kCancelButtonLabel", comment: "Decline Button")
    SwiftyiRate.sharedSwiftyiRate.remindButtonLabel = NSLocalizedString("kRemindButtonLabel", comment: "Remind Button")
    SwiftyiRate.sharedSwiftyiRate.rateButtonLabel = NSLocalizedString("kRateButtonLabel", comment: "Rate Button")
}

Example Projects

所有的示例工程都设置了previewMode为true，所以会出现一启动就提示评分情况。

Advanced Example

高级示例用于测试SwiftyiRateDelegate和自定义逻辑

Release Notes

Version 1.0

• Initial release.