Skip to main content
Version: v4

iOS SDK 开发指南

本文介绍如何在游戏中加入成就系统。

集成前准备​

  1. 参考 开发者中心配置 创建应用、配置包名与签名证书
  2. 参考 成就系统功能介绍开通成就系统服务
  3. 参考 iOS 集成指南 完成基础接入
  4. 成就模块依赖于 TapTap 登录模块，开发者接入前应先完成 TapTap 登录的接入

SDK 获取​

远程依赖​

  1. 在工程 Podfile 文件中对应模块下添加依赖：
 pod 'TapTapSDK/Achievement', '~> 4.11.1'
  1. 执行 Pod install 下载对应依赖文件

本地文件依赖​

成就系统依赖于初始化和 TapTap 登录模块，使用本地文件方式添加依赖时，需先参考集成指南 和 TapTap 登录添加对应本地文件依赖项。

  1. 在下载页下载如下文件：
  • TapTapAchievementSDK.xcframework 成就依赖库
  • TapTapAchievementResource.bundle 成就资源文件
  1. 在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed，导入 bundle 资源文件

初始化额外配置​

在调用业务接口前，开发者需先调用初始化接口完成应用信息的配置，示例如下：

import TapTapAchievementSDK
import TapTapCoreSDK

// 核心配置
let coreOptions = TapTapSdkOptions()
coreOptions.clientId = "your_client_id" // 必须，开发者中心对应 Client ID
coreOptions.clientToken = "your_client_token" // 必须，开发者中心对应 Client Token

// 成就配置
let achievementOptions = TapTapAchievementOptions()
// 成就达成时 SDK 是否需要展示一个气泡弹窗提示
achievementOptions.enableToast = true

// 其他模块配置项
let otherOptions = [achievementOptions]

// TapSDK 初始化
TapTapSDK.initWith(coreOptions, otherOptions: otherOptions)

注册监听回调​

成就 SDK 中包含多个监听回调，分别会在初始化数据成功、初始化数据失败以及成就进度更新时被调用。

import TapTapAchievementSDK

class CallbackImpl: NSObject, TapTapAchievementCallback {

    override init() {}
    
    // 成就状态更新成功
    func onAchievementSuccess(code: Int, result: TapTapAchievementResult) {
        // code 70001 解锁成就成功
        // code 70002 增加步长成功
        // result 成就数据详情
    }
    
    // 成就状态更新失败或其他错误    
    func onAchievementFailure(achievementId: String, errorCode: Int, errorMsg: String) {
        // achievementId 触发失败的成就 ID， 如果调用的是 [ShowAchievements] 接口，则为 "" 空字符串。
        // errorCode 错误码
        // errorMsg 错误描述
    }
}
let callback = CallbackImpl()
TapTapAchievement.registerCallback(callback: callback)

// 不需要接收回调时调用接口移除之前设置的回调对象
TapTapAchievement.unregisterCallback(callback: callback)

成就常量定义：

public class TapAchievementCallbackCode: NSObject {
    // 解锁成就成功，包括步长达到阈值解锁和直接解锁
    public static let UNLOCK_SUCCESS = 70001
    
    // 增加步长成功
    public static let INCREMENT_SUCCESS = 70002
    
    // 上报失败，未初始化
    public static let NOT_INITIALIZED = 80000
    
    // 区域不支持
    public static let REGION_NOT_SUPPORTED = 80001
    
    // 上报失败，未登录
    public static let NOT_LOGGED = 80002
    
    // 认证信息无效
    public static let ACCESS_DENIED = 80010
    
    // 无效请求
    public static let INVALID_REQUEST = 80020
    
    // 网络异常
    public static let NETWORK_ERROR = 80030
    
    // 未知异常
    public static let UNKNOWN_ERROR = 80100
}

成功数据详情​

TapAchievementResult

字段含义
achievementId成就id
achievementName成就名称
achievementType成就类型，分为普通成就（TapAchievementType.NORMAL）、白金成就（TapAchievementType.PLATINUM）
currentSteps当前成就进度，如果不是分步式成就该值为 0

错误码详情​

errorCode错误类型错误原因
80000NOT_INITIALIZED未初始化，在调用API之前请先初始化
80001REGION_NOT_SUPPORTED区域不支持，成就目前只支持区域 CN , 请确认初始化参数 region
80002NOT_LOGGED当前未登录，请在登录之后再使用报错API
80010ACCESS_DENIED当前登录失效，需要重新登录
80020INVALID_REQUEST无效参数，请检查传入的参数是否正确
80030NETWORK_ERROR网络异常, 请确认当前网络连接是否正常
80100UNKNOWN_ERROR请确认当前网络连接是否正常 ，或者联系技术支持

解锁某个成就​

当玩家达成某一成就时，可以使用以下方式解锁成就，解锁成功后会触发 callback 的 OnAchievementSuccess 回调。 解锁失败会触发 callback 的 OnAchievementFailure 回调。具体错误码请参考 错误码详情

import TapTapAchievementSDK

// achievementId 是在开发者中心中添加成就时自行设定的成就 Id
TapTapAchievement.unlock(achievementId: achievementId)

分步成就增长步数​

如果成就是增量类型（即，需要几个步骤才能解锁它）请使用以下API。SDK 会自动计算当前全量步数。 解锁成功后会触发 callback 的 OnAchievementSuccess 回调。 解锁失败会触发 callback 的 OnAchievementFailure 回调。具体错误码请参考 错误码详情

import TapTapAchievementSDK

// achievementId 为在开发者中心中添加成就时自行设定的成就 Id
let achievementId = "achievementId"
// steps 为增长的步数
let steps = 1
// 更新成就步长数据
TapTapAchievement.increment(achievementId: achievementId, steps: steps)

设置冒泡开关​

默认情况下，成就达成时 SDK 会自行展示一个冒泡浮窗提示玩家已达成相应成就。需要关闭请调用如下接口或者在初始化的时候设置 TapTapAchievementOptions.enableToast 为 false。 详见 成就初始化配置

import TapTapAchievementSDK

TapTapAchievement.setToastEnable(enable: false)

打开成就展示页​

SDK 自带一个展示所有成就和已达成成就情况的页面。 当玩家设备上有安装TapTap客户端时，会跳转到TapTap客户端的成就页面，否则会在游戏内展示成就页面。

import TapTapAchievementSDK

TapTapAchievement.showAchievements()

国际化​

TapTapAchievement 支持设置语言：目前只支持简体中文