Authorizing the iOS SDK

The iOS SDK provides Swift 5 classes and methods to access the PureCloud Platform API. This tutorial will demonstrate how a user can authorize the SDK using the OAuth Implicit Grant or the OAuth PKCE Grant in a Swift 5 iOS app using Swift's WKWebView in-app web browser. The use of OAuth PKCE Grant is recommended (and enabled by default in the sample application) as it provides a more secure option for client-side applications.

For more information about the SDK, see the PureCloud iOS SDK on the Developer Center.

The Platform API Client SDK for iOS is added to Swift projects using CocoaPods.

Navigate to the root of your sample project and initialize CocoaPods:

pod init

Reference the SDK's pod in your project's Podfile, running:

pod 'PureCloudPlatformClientV2', :git => 'https://github.com/MyPureCloud/platform-client-sdk-ios.git', :tag => '136.0.0'

Then install your project's dependencies:

pod install

These initial pod init and pod install steps have already been performed in the sample project available in https://github.com/MyPureCloud/quick-hits-extras/tree/main/swift/ios-pkce-auth

You can then open the gc-auth-ios.xcworkspace file from XCode.

A version of the iOS project, that supports the OAuth Implicit Grant and PKCE Grant flows, but that does not reference and use the Platform API Client SDK (before pod init and pod install), is also available in https://github.com/MyPureCloud/quick-hits-extras/tree/main/swift/ios-pkce-auth/project-before-cocoa-pod/gc-auth-ios

This sample application supports both the OAuth Implicit Grant flow (legacy) to allow the user to to authorize the SDK, and the OAuth PKCE Grant flow (recommended).

Genesys Cloud enviroment parameters can be defined in the gc-auth-config/Development.cxconfig file:

1. Set the region of your Genesys Cloud organization with GC_ENVIRONMENT(e.g. mypurecloud.com, mypurecloud.ie, mypurecloud.de, ...).
2. Set your OAuth's Client ID with GC_CLIENT_ID (i.e. replace YOUR_OAUTH_CLIENT_ID with the Client ID of your OAuth Client)
3. GC_REDIRECT_URL defines the Authorized Redirect URI set in your OAuth Client. You can use https://fakeredirecturi/oauth2/callbackas defined here.
4. Define if the application will use an OAuth PKCE Grant flow (GC_USE_PKCE=true) or an OAuth Implicit Grant flow (GC_USE_PKCE=false)

Please note that the application also supports two optional parameters (meaningful for Genesys Cloud orginizations using SSO): GC_USE_ORG and GC_USE_PROVIDER that you can use to specify your target organization.

For OAuth PKCE Grant flow, Create an OAuth Client with Grant Type: Code Authorization.

For OAuth Implicit Grant flow, Create an OAuth Client with Grant Type: Token Implicit Grant.

The redirect URI used by this application, and configured on the OAuth client, is http://fakeredirecturi/oauth2/callback. In a future step, the application will check for this fake URI and end the authorization process when navigation is referred to this URI.

The application is then initialized with the values defined in the gc-auth-config/Development.cxconfig file:

When the user presses the Login button, the application constructs the URL to initiate the OAuth flow, unhides the embedded web browser, and navigates it to the authorization URL using webGCAuthView.load(gcLoginRequest).

The Login URL is created according to the Genesys Cloud region, the OAuth Client ID and chosen Grant type (PKCE Grant or Implicit Grant).

The WKWebView object allows the view controller to intercept navigation requests. This code will allow all navigation requests by default (except on the configured Redirect URI).

When the configured redirect URI is encountered, the code checks for the presence of an access token (in case of an OAuth Implicit Grant flow) or for the presence of an authorization code (in case of an OAuth PKCE Grant flow).

With OAuth Implicit Grant flow, if the access token is found, it is extracted from the URL.

With OAuth PKCE Grant flow, if a code is found, the application will make a request to Genesys Cloud to obtain an access token from this code (second step of the OAuth PKCE Grant flow).

On loggedin custom UI event, the application sets the token on the SDK using PureCloudPlatformClientV2API.accessToken = self.gcAuthManager.accessToken.

The web view is then hidden and navigation canceled. At this point, the SDK is now authorized and may begin making API requests.

This section demonstrates using the SDK to make authenticated requests to the PureCloud Platform API.

First, a request is made to UsersAPI.getUsersMe(expand: expand) (GET /api/v2/users/me). If this request is successful, the user's name from the response is used to populate a label in the UI. Additionally, if the response contains a profile image, it will be downloaded and displayed in a UIImageView in the UI.