Set up iOS SDK

This document will introduce how to configure the iOS SDK for QWeather API.

OS Requirement:

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

Step 1: Create project and credential

Make sure you have created a Project and Credential, see Project and KEY and JWT authentication.

Step 2: Install SDK

The latest version of iOS SDK is 5.1.0(Release note), and it supports the following installation methods:

Swift Package Manager

You can also use Swift Package Manager to integrate iOS SDK, please refer to Adding package dependencies to your app.

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

CocoaPods

QWeather iOS SDK can be installed via CocoaPods. CocoaPods is an open source dependency manager, if you haven’t installed CocoaPods yet, please refer to CocoaPods Getting Started guide. The following steps assume that you have already completed the installation and setup of CocoaPods.

1. Create a file named Podfile in your project directory
2. Add the following to the Podfile and save it
   • 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
     

3. Open a terminal and go to the directory containing the Podfile and run:

   pod install
   

Update SDK

Open a terminal and go to the directory containing the Podfile and run:

pod update

Manual install

1. Download SDK: QWeatherSDK 5.1.0
2. Add QWeatherSDK.xcframework to iOS/macOS Target.

Step 3: Add API Host and token

Initialize the QWeather instance.

Replace YOUR_HOST with your API Host.

Swift

import QWeatherSDK

...

try await QWeather
            .getInstance("{YOUR_HOST}")  // Initialize api host
            .setupLogEnable(true)  // Enable debug logging (set false for production environments)

Objective-C

#import <QWeatherSDK/QWeatherSDK-Swift.h>

...

// Initialize api host
[QWeatherObjc initConfigWithHost:@"{YOUR_HOST}"];

// Enable debug logging (set false for production environments)
[QWeatherObjc setupLogEnable:YES];

Set up the token generator

Hint: iOS SDK only support JWT for authentication.

The SDK provides two token generation mechanisms: TokenGenerator and closure-based implementation. Developers can choose either approach based on their needs. It is important to note that if both methods are configured simultaneously, the closure implementation will be automatically disabled. For security purposes, please ensure proper management of sensitive information such as private key, project ID, and credential ID, avoiding storage or transmission in plaintext.

Swift

// Configure the token generator using the JWTGenerator class provided by the SDK
let jwt = JWTGenerator(privateKey: "{YOUR_PRIVATE_KEY}", // Pravite Key
                              pid: "{YOUR_PROJECT_ID}", // Project ID
                              kid: "{YOUR_KID}") // Credential ID
instance.setupTokenGenerator(jwt)

//NOTE: Developers can also customize a token generator by conforming to the TokenGenerator protocol.

// Set the token generator via a closure.
instance.setupTokenGenerator({  
     // Update jwt token should be implemented here in production environments
      return "{YOUR_TOKEN}"
})

Objective-C

// Set the token generator using the method provided by the SDK.
[QWeatherObjc setupTokenGeneratorWithPrivateKey:@"{YOUR_PRIVATE_KEY}" // Pravite Key
                                          pid:@"{YOUR_PROJECT_ID}" // Project ID
                                          kid:@"{YOUR_KID}"]; // Credential ID


// Set the token generator via a closure.
[QWeatherObjc setupTokenGeneratorWithGenerater:^NSString * _Nonnull{
    // Update jwt token should be implemented here in production environments
    return @"{YOUR_TOKEN}"; 
}];

Sample code

Get real-time weather for Beijing.

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);
    }
}];