# goeasy-swift

**Repository Path**: goeasy-io/goeasy-swift

## Basic Information

- **Project Name**: goeasy-swift
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GoEasy iOS SDK

GoEasy 的 iOS 原生 SDK，对外提供纯 Swift API。

- **纯 Swift**：API 与回调都是原生 Swift，不兼容 ObjC
- **要求**：iOS 13.0+，Xcode 13.0+

## 本仓内容

本仓只放分发产物，不含 Swift 源码：

| 文件 | 说明 |
|---|---|
| `GoEasySDK.xcframework` | 静态 framework，双平台（真机 + 模拟器），官方分发产物 |
| `Package.swift` | SPM 的 `binaryTarget` 声明 |
| `GoEasySDK.podspec` | CocoaPods 的 `:git` 分发声明 |

tag 即版本号（无 `v` 前缀）。下文出现的版本号就是本仓最新发布版本，接入时按需换成你要用的那个。

## 集成

### Swift Package Manager

```swift
.package(url: "https://gitee.com/goeasy-io/goeasy-swift.git", from: "0.1.0")
```

### CocoaPods

```ruby
pod 'GoEasySDK', :git => 'https://gitee.com/goeasy-io/goeasy-swift.git', :tag => '0.1.0'
```

### 手动集成

下载 `GoEasySDK.xcframework` 拖入工程，在 target 的 **Frameworks, Libraries, and Embedded Content** 中选择 **Embed & Sign**。

> **静态 framework 需要嵌入**：`GoEasySDK.xcframework` 是静态的，不会自动进入 App bundle。用 Xcode 15+ 时勾选 Embed & Sign 即可；Xcode 13/14 需要手动把 `GoEasySDK.framework/PrivacyInfo.xcprivacy` 加进 App target 的 Copy Bundle Resources，否则隐私清单到不了 App 包内。

## 快速开始

```swift
import GoEasySDK

// App 启动时初始化（主线程）。三个参数都没有默认值
try GoEasy.initSDK(host: "你的Host", appkey: "你的AppKey", notification: true)

// 建立连接
GoEasy.connect { result in
    switch result {
    case .success: print("连接成功")
    case .failure(let error): print("连接失败: \(error.code) \(error.message)")
    }
}

// 订阅频道
GoEasy.ws?.subscribe(
    channels: ["my_channel"],
    onMessage: { message in
        print("收到消息: \(message.channel ?? "-") \(message.content)")
    },
    completion: { result in
        if case .failure(let error) = result { print("订阅失败: \(error.message)") }
    }
)

// 发布消息
GoEasy.ws?.publish(options: PublishOptions(channel: "my_channel", message: "hello")) { result in
    if case .failure(let error) = result { print("发送失败: \(error.code) \(error.message)") }
}
```

`ws` 与 `notification` 都是可选属性：

- `notification` 只在 `initSDK` 传了 `notification: true` 时才非 nil
- `initSDK` 抛错时，`notification` 可能已经建好而 `ws` 仍为 nil——两者不是对称状态，失败后请以 `initSDK` 抛出的错误为准，不要碰这两个属性
- 未初始化就调用 `connect`/`disconnect`，错误通过 completion 以 `code = "400"` 返回（不传 completion 则错误被丢弃）；`initSDK` 本身是抛错的

## API 概览

```swift
// 生命周期
GoEasy.initSDK(host: String, appkey: String, notification: Bool) throws
GoEasy.connect(options: ConnectOptions = ConnectOptions(), completion: ((Result<Void, GoEasyError>) -> Void)? = nil)
GoEasy.disconnect(completion: ((Result<Void, GoEasyError>) -> Void)? = nil)

// 发布订阅（GoEasy.ws）
GoEasy.ws?.publish(options: PublishOptions, completion: ((Result<Void, GoEasyError>) -> Void)? = nil)
GoEasy.ws?.subscribe(channels: [String], onMessage: @escaping (WSMessage) -> Void, completion: ((Result<Void, GoEasyError>) -> Void)? = nil)
GoEasy.ws?.unsubscribe(options: UnSubscribeOptions, completion: ((Result<Void, GoEasyError>) -> Void)? = nil)
GoEasy.ws?.history(options: HistoryOptions, completion: @escaping (Result<WSMessageHistory, GoEasyError>) -> Void)

// 推送（GoEasy.notification，initSDK 传 notification: true 才有）
GoEasy.notification?.registerDeviceToken(_ deviceToken: Data)
GoEasy.notification?.setBadge(options: BadgeOptions, completion: ((Result<Void, GoEasyError>) -> Void)? = nil)
GoEasy.notification?.onClick(callBack: @escaping (String) -> Void)
```

### 参数与结果类型

全部是 `struct`，成员只读；默认值齐全，可按需省略尾部参数。

| 类型 | 字段 |
|---|---|
| `ConnectOptions` | `id: String?`、`data: String?`、`otp: String?` |
| `PublishOptions` | `channel: String`、`message: String`、`qos: Int?`、`notification: NotificationOptions?` |
| `NotificationOptions` | `title: String`、`body: String`、`sound: String?`、`badge: String?`、`vendorOptions: [String: Any]?` |
| `UnSubscribeOptions` | `channel: String`（一次只能退订一个频道） |
| `HistoryOptions` | `channel: String`、`start: Int64?`、`end: Int64?`、`limit: Int?` |
| `WSMessage` | `time: Int64`、`channel: String?`（历史消息可能为 nil）、`content: String` |
| `WSMessageHistory` | `messages: [WSMessage]` |
| `BadgeOptions` | `badge: Int` |
| `GoEasyError` | `code: String`、`message: String`；`errorDescription` 输出 `[code] message` |

## 推送通知

**不需要手动向系统注册**：`initSDK(notification: true)` 内部已完成注册。AppDelegate 收到 device token 时调用 `registerDeviceToken(_:)`，通知点击回放用 `onClick(callBack:)`。

- 完整接入步骤（权限、AppDelegate、推送回执）：[GoEasy 官方文档](https://www.goeasy.io/)
- 可运行的 SwiftUI 推送范例：[websocket-helloworld](https://github.com/goeasy-io/websocket-helloworld)

## License

MIT，见 [LICENSE](LICENSE)。