编辑

iOS SDK配置

这篇文档将介绍如何配置和风天气开发服务中的iOS SDK。

隐私声明：和风天气iOS SDK不需要电话、位置、设备唯一标识符等任何特殊权限，我们不会也无法通过本SDK收集用户隐私信息。

和风天气iOS SDK支持下列操作系统：

iOS 15.0+
macOS 11.0+
tvOS 15.0+
watchOS 8.0+
visionOS 1.0+

第1步: 创建项目和凭据

请确保已经创建了项目和凭据，并已了解如何使用JWT身份认证。

第2步: 安装SDK

当前iOS SDK的最新版本是5.1.0(更新记录)，支持下列安装方式：

Swift Package Manager

iOS SDK支持使用Swift Package Manager集成，具体步骤请参考Adding package dependencies to your app

SDK URL: https://github.com/qwd/qweather-ios-sdk.git
Dependency Rule: Required 5.1.0

CocoaPods

和风天气iOS SDK可以通过CocoaPods进行安装。CocoaPods是一种开源依赖库管理器，如果你还未安装CocoaPods，请参考CocoaPods快速开始。下列步骤假设你已经完成了CocoaPods的安装和设置。

在项目根目录创建名为Podfile的文件

在Podfile文件中添加如下内容并保存：

iOS

target '{YOUR_iOS_TARGET}' do
   pod 'QWeather-SDK','~> 5.1.0'
end

macOS

target '{YOUR_macOS_TARGET}' do
   pod 'QWeather-SDK','~> 5.1.0'
end

打开终端，进入包含Podfile的目录
- 运行：
```
 pod install
```

更新SDK

打开终端，进入包含Podfile的目录，运行：

pod update

手动安装

你可以选择手动安装和风天气iOS SDK。

下载SDK：QWeatherSDK 5.1.0
将 QWeatherSDK.xcframework 包导入到iOS或macOS Target中

第3步: 添加API Host和Token

初始化QWeather实例

将代码中的YOUR_HOST替换为您的API Host

Swift

import QWeatherSDK

...

try await QWeather
            .getInstance("{YOUR_HOST}")  // 初始化服务地址
            .setupLogEnable(true)  // 启用调试日志（生产环境建议设置为 false）

Objective-C

#import <QWeatherSDK/QWeatherSDK-Swift.h>

...

// 初始化服务地址
[QWeatherObjc initConfigWithHost:@"{YOUR_HOST}"];

// 启用调试日志（生产环境建议设置为 false）
[QWeatherObjc setupLogEnable:YES];

设置Token生成器

提示：iOS SDK仅支持JWT身份认证。

SDK支持通过TokenGenerator和闭包两种机制生成访问令牌，开发者可根据需求任选其一。需注意当同时配置两种方式时，闭包实现将自动失效。出于安全考虑，请确保妥善保管私钥、项目ID及凭据ID等敏感信息，避免以明文形式存储或传输。

Swift

// 通过SDK提供的JWTGenerator设置令牌生成器，其遵从TokenGenerator协议
let jwt = JWTGenerator(privateKey: "{YOUR_PRIVATE_KEY}", // 私钥
                              pid: "{YOUR_PROJECT_ID}", // 项目ID
                              kid: "{YOUR_KID}") // 凭据ID
instance.setupTokenGenerator(jwt)

//NOTE: 开发者也可以通过遵从TokenGenerator协议创建自己的令牌生成器

// 通过闭包设置令牌生成器
instance.setupTokenGenerator({  
    // 生产环境中应在此处实现令牌刷新逻辑，而非硬编码
    return "{YOUR_TOKEN}"  // 返回用于 API 认证的 JWT 令牌
})

Objective-C

// 通过SDK提供的方法设置令牌生成器
[QWeatherObjc setupTokenGeneratorWithPrivateKey:@"{YOUR_PRIVATE_KEY}" // 私钥
                                          pid:@"{YOUR_PROJECT_ID}" // 项目ID
                                          kid:@"{YOUR_KID}"]; // 凭据ID


// 通过闭包设置令牌生成器
[QWeatherObjc setupTokenGeneratorWithGenerater:^NSString * _Nonnull{
    // 生产环境中应在此处实现令牌刷新逻辑，而非硬编码
    return @"{YOUR_TOKEN}"; // 返回用于 API 认证的 JWT 令牌
}];

示例代码

请求北京实时天气。

Swift

import QWeatherSDK

...

Task {
    do {
        let parameter = WeatherParameter(location: "101010100")
        let response = try await QWeather.instance.weatherNow(parameter)
        print(response)
    } catch QWeatherError.errorResponse(let error) {
        print(error)
    } catch {
        print(error)
    }
}

Objective-C

#import <QWeatherSDK/QWeatherSDK-Swift.h>

...

WeatherParameter *parameter = [WeatherParameter instanceWithLocation:@"101010100" lang:@(LangZH_HANS) unit:@(UnitMETRIC)];
[QWeatherObjc weatherNow:parameter completionHandler:^(WeatherNowResponse * _Nullable response, NSError * _Nullable error) {
    if (response) {
        NSLog(@"%@", response.description);
    }
    if (error) {
        NSLog(@"%@", error.localizedDescription);
    }
}];