概述
欢迎使用纸飞机API！本快速开始指南将帮助您在短时间内完成纸飞机API的基本集成，让您的应用能够立即开始使用纸飞机的强大功能。
本指南假设您已经熟悉基本的移动应用或Web应用开发。如果您是初学者，建议先学习相关平台的基础知识。
您将学到什么
- 如何创建纸飞机开发者账号
- 如何创建和配置应用
- 如何安装和初始化纸飞机SDK
- 如何实现用户认证
- 如何发送和接收消息
所需时间
完成本指南的所有步骤大约需要15分钟，前提是您已经准备好开发环境。
前提条件
在开始之前，请确保您满足以下要求：
开发环境要求
- iOS开发：
- macOS系统
- Xcode 12.0或更高版本
- iOS 13.0或更高版本
- CocoaPods 1.10.0或更高版本
- Android开发：
- Android Studio 4.0或更高版本
- Android 6.0 (API级别23)或更高版本
- Java 8或Kotlin
- Gradle 6.0或更高版本
- Web开发：
- 现代浏览器（Chrome、Firefox、Safari、Edge等）
- Node.js 14.0或更高版本
- NPM或Yarn包管理器
其他要求
- 有效的电子邮件地址（用于创建开发者账号）
- 应用的基本信息（名称、描述、图标等）
- 应用的包名/包标识符（iOS: Bundle ID, Android: Package Name, Web: 域名）
创建应用
账号激活后，您需要在开发者平台创建一个新的应用，以获取API密钥和其他必要的凭证。
操作步骤
- 登录 纸飞机开发者平台
- 在控制台页面，点击"创建新应用"按钮
- 填写应用信息：
- 应用名称（将显示给用户）
- 应用描述（简要介绍您的应用）
- 应用类型（iOS、Android、Web或其他）
- 包名/包标识符（根据您的平台填写）
- 应用图标（可选，建议上传）
- 选择您需要的API权限（至少选择"基础权限"和"消息权限"）
- 点击"创建应用"按钮
获取凭证
应用创建成功后，您将看到以下重要凭证：
- Client ID：应用的唯一标识符
- Client Secret：用于服务器端API调用的密钥（请妥善保管）
- API Key：用于客户端SDK初始化的密钥
- Redirect URI：OAuth认证使用的重定向URI
Client Secret非常重要，请不要在客户端代码中硬编码，只能在服务器端使用。
安装SDK
根据您的开发平台，选择并安装相应的纸飞机SDK。
iOS (使用CocoaPods)
# 在Podfile中添加 pod 'PaperPlaneSDK', '~> 8.0'
然后在终端中运行：
pod install
Android (使用Gradle)
在项目级别的build.gradle文件中添加：
allprojects {
repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
在应用级别的build.gradle文件中添加：
dependencies {
implementation 'com.paperplane:sdk:8.0.0'
}
Web (使用NPM)
npm install paperplane-sdk --save
或者使用Yarn：
yarn add paperplane-sdk
请始终使用最新版本的SDK，以获取最新的功能和安全更新。
初始化SDK
安装完成后，您需要在应用启动时初始化纸飞机SDK。
iOS (Swift)
import PaperPlaneSDK
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// 初始化纸飞机SDK
PaperPlaneSDK.initialize(
apiKey: "YOUR_API_KEY",
clientId: "YOUR_CLIENT_ID",
environment: .production // 或 .sandbox 用于测试
)
return true
}
}
Android (Kotlin)
import com.paperplane.sdk.PaperPlaneSDK
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
// 初始化纸飞机SDK
PaperPlaneSDK.initialize(
context = this,
apiKey = "YOUR_API_KEY",
clientId = "YOUR_CLIENT_ID",
environment = PaperPlaneSDK.Environment.PRODUCTION // 或 SANDBOX 用于测试
)
}
}
并在AndroidManifest.xml中添加：
<application
android:name=".MyApplication"
>
Web (JavaScript)
import { PaperPlaneSDK } from 'paperplane-sdk';
// 初始化纸飞机SDK
PaperPlaneSDK.initialize({
apiKey: 'YOUR_API_KEY',
clientId: 'YOUR_CLIENT_ID',
environment: 'production' // 或 'sandbox' 用于测试
});
请确保使用正确的API Key和Client ID，否则SDK将无法正常工作。
用户认证
接下来，您需要实现用户认证功能，让用户能够登录到纸飞机。
iOS (Swift)
// 手机号登录
PaperPlaneSDK.auth.loginWithPhone(
phone: "+8613800138000",
verificationCode: "123456"
) { result in
switch result {
case .success(let user):
print("登录成功: \(user)")
// 保存用户信息和令牌
case .failure(let error):
print("登录失败: \(error.localizedDescription)")
}
}
// 或者使用二维码登录
let qrCodeUrl = PaperPlaneSDK.auth.generateQRCodeUrl()
// 显示二维码给用户扫描
// 然后轮询登录状态
PaperPlaneSDK.auth.checkQRCodeLoginStatus { result in
switch result {
case .success(let user):
print("二维码登录成功: \(user)")
case .failure(let error):
print("二维码登录失败: \(error.localizedDescription)")
}
}
Android (Kotlin)
// 手机号登录
PaperPlaneSDK.auth.loginWithPhone(
phone = "+8613800138000",
verificationCode = "123456",
callback = object : AuthCallback {
override fun onSuccess(user: User) {
Log.d("PaperPlane", "登录成功: $user")
// 保存用户信息和令牌
}
override fun onFailure(error: PaperPlaneException) {
Log.e("PaperPlane", "登录失败: ${error.message}")
}
}
)
// 或者使用二维码登录
val qrCodeUrl = PaperPlaneSDK.auth.generateQRCodeUrl()
// 显示二维码给用户扫描
// 然后轮询登录状态
PaperPlaneSDK.auth.checkQRCodeLoginStatus(object : AuthCallback {
override fun onSuccess(user: User) {
Log.d("PaperPlane", "二维码登录成功: $user")
}
override fun onFailure(error: PaperPlaneException) {
Log.e("PaperPlane", "二维码登录失败: ${error.message}")
}
})
Web (JavaScript)
// 手机号登录
PaperPlaneSDK.auth.loginWithPhone({
phone: '+8613800138000',
verificationCode: '123456'
})
.then(user => {
console.log('登录成功:', user);
// 保存用户信息和令牌
})
.catch(error => {
console.error('登录失败:', error.message);
});
// 或者使用重定向登录
const redirectUrl = PaperPlaneSDK.auth.getRedirectUrl();
window.location.href = redirectUrl;
// 在重定向回来的页面处理登录结果
PaperPlaneSDK.auth.handleRedirectCallback()
.then(user => {
console.log('重定向登录成功:', user);
})
.catch(error => {
console.error('重定向登录失败:', error.message);
});
登录成功后，SDK会自动保存用户的访问令牌和刷新令牌。您可以使用PaperPlaneSDK.auth.getCurrentUser()获取当前登录用户的信息。
发送第一条消息
现在，让我们发送您的第一条消息！
iOS (Swift)
// 创建一个用户会话
let chatId = "user_1234567890" // 接收者的用户ID
// 发送文本消息
PaperPlaneSDK.messages.sendMessage(
chatId: chatId,
type: .text,
content: ["text": "你好，这是我的第一条消息！"]
) { result in
switch result {
case .success(let message):
print("消息发送成功: \(message)")
case .failure(let error):
print("消息发送失败: \(error.localizedDescription)")
}
}
Android (Kotlin)
// 创建一个用户会话
val chatId = "user_1234567890" // 接收者的用户ID
// 发送文本消息
val content = mapOf("text" to "你好，这是我的第一条消息！")
PaperPlaneSDK.messages.sendMessage(
chatId = chatId,
type = MessageType.TEXT,
content = content,
callback = object : MessageCallback {
override fun onSuccess(message: Message) {
Log.d("PaperPlane", "消息发送成功: $message")
}
override fun onFailure(error: PaperPlaneException) {
Log.e("PaperPlane", "消息发送失败: ${error.message}")
}
}
)
Web (JavaScript)
// 创建一个用户会话
const chatId = 'user_1234567890'; // 接收者的用户ID
// 发送文本消息
PaperPlaneSDK.messages.sendMessage({
chatId: chatId,
type: 'text',
content: {
text: '你好，这是我的第一条消息！'
}
})
.then(message => {
console.log('消息发送成功:', message);
})
.catch(error => {
console.error('消息发送失败:', error.message);
});
请确保接收者的用户ID是正确的，并且您有权限向该用户发送消息。
接收消息
最后，让我们设置消息接收器，以便接收来自其他用户的消息。
iOS (Swift)
// 设置消息接收器
class MessageReceiver: MessageListener {
func onMessageReceived(_ message: Message) {
print("收到新消息: \(message)")
// 处理新消息
}
func onMessageStatusUpdated(_ messageId: String, status: MessageStatus) {
print("消息状态更新: \(messageId) - \(status)")
// 处理消息状态更新
}
func onTypingStatusUpdated(_ chatId: String, isTyping: Bool) {
print("输入状态更新: \(chatId) - \(isTyping)")
// 处理输入状态更新
}
}
// 注册消息接收器
let receiver = MessageReceiver()
PaperPlaneSDK.messages.addMessageListener(receiver)
Android (Kotlin)
// 设置消息接收器
class MessageReceiver : MessageListener {
override fun onMessageReceived(message: Message) {
Log.d("PaperPlane", "收到新消息: $message")
// 处理新消息
}
override fun onMessageStatusUpdated(messageId: String, status: MessageStatus) {
Log.d("PaperPlane", "消息状态更新: $messageId - $status")
// 处理消息状态更新
}
override fun onTypingStatusUpdated(chatId: String, isTyping: Boolean) {
Log.d("PaperPlane", "输入状态更新: $chatId - $isTyping")
// 处理输入状态更新
}
}
// 注册消息接收器
val receiver = MessageReceiver()
PaperPlaneSDK.messages.addMessageListener(receiver)
Web (JavaScript)
// 设置消息接收器
PaperPlaneSDK.messages.on('message', (message) => {
console.log('收到新消息:', message);
// 处理新消息
});
PaperPlaneSDK.messages.on('message_status', (data) => {
console.log('消息状态更新:', data.messageId, '-', data.status);
// 处理消息状态更新
});
PaperPlaneSDK.messages.on('typing', (data) => {
console.log('输入状态更新:', data.chatId, '-', data.isTyping);
// 处理输入状态更新
});
不要忘记在适当的时候移除消息接收器，以避免内存泄漏。
后续步骤
恭喜！您已经成功完成了纸飞机API的基本集成。现在，您可以继续探索纸飞机的更多高级功能。
推荐的后续步骤
- 群组聊天：学习如何创建和管理群组聊天
- 多媒体消息：学习如何发送和接收图片、视频、音频等多媒体消息
- 文件传输：学习如何发送和接收文件
- 语音和视频通话：学习如何实现语音和视频通话功能
- 推送通知：学习如何集成推送通知功能
- 离线消息：学习如何处理离线消息
参考文档
故障排除
如果您在集成过程中遇到问题，请参考以下常见问题和解决方案。
常见问题及解决方案
| 问题 | 可能的原因 | 解决方案 |
|---|---|---|
| SDK初始化失败 | API Key或Client ID不正确 | 检查您的API Key和Client ID是否正确，确保没有多余的空格或特殊字符 |
| 登录失败 | 手机号或验证码不正确 | 确保手机号格式正确（包含国际区号），验证码有效且未过期 |
| 消息发送失败 | 接收者ID不正确或没有权限 | 检查接收者ID是否正确，确保您有权限向该用户发送消息 |
| 无法接收消息 | 消息接收器未正确注册或网络连接问题 | 确保消息接收器已正确注册，检查网络连接是否正常 |
| 应用崩溃 | SDK版本与系统不兼容 | 确保使用最新版本的SDK，检查SDK的系统要求是否与您的应用兼容 |
获取帮助
如果您遇到的问题不在上述列表中，或者解决方案不起作用，请尝试以下方法获取帮助：
联系支持时，请提供尽可能详细的信息，包括错误日志、SDK版本、设备信息等，以便我们能够更好地帮助您解决问题。
常见问题
1. 纸飞机API支持哪些平台？
纸飞机API支持iOS、Android、Web、Windows、macOS和Linux等主流平台。我们提供相应的SDK和API文档，帮助您在不同平台上进行集成。
2. 纸飞机API是否免费？
纸飞机API提供免费和付费两种计划。免费计划包含基本功能，适合小型应用或开发测试。付费计划提供更多高级功能和更高的API调用限额，适合生产环境和大型应用。详情请查看定价页面。
3. 如何获取API调用限额？
您可以在开发者平台的应用详情页面查看当前的API调用限额和使用情况。如果需要更高的限额，可以升级到付费计划或联系我们的销售团队。
4. 如何处理离线消息？
纸飞机SDK会自动处理离线消息。当用户重新上线时，SDK会自动同步离线期间收到的消息。您也可以使用PaperPlaneSDK.messages.getMessages()方法手动获取历史消息。
5. 如何实现推送通知？
纸飞机SDK支持与各平台的推送通知服务集成，包括APNs（iOS）、FCM（Android）和Web Push（Web）。请参考推送通知指南了解详细的集成步骤。
6. 如何确保消息的安全性？
纸飞机使用端到端加密技术保护所有消息。消息在发送前在客户端加密，只有接收者才能解密和阅读。服务器无法查看消息的实际内容。此外，您还可以实现阅后即焚功能，让消息在被阅读后自动删除。
有问题或建议？
帮助我们改进文档，提供反馈或寻求支持