SDK 3.0 migration guide

This document outlines the new features in the v3.0.0 SDK release, and the changes that are required to implement them.

The main change implemented in the new Zettle SDK is the support for secure authorisation through OAuth 2.0. Previously, authorisation and authentication in the Zettle SDK behaved pretty much like a black box — the SDK managed the process completely by itself and integrators had no way of controlling or influencing that process. While easy to use, this had a few downsides:

• Poor seller experience — Sellers routinely had to maintain two logins—one for their POS app and one for the Zettle SDK. Switching accounts between them was not a great experience either since it often happen that sellers only change their POS app account and not their SDK account.
• Poor partner experience — Partners had no way of controlling or knowing which users are logged in the SDK since all interaction with the SDK was always done by the sellers.

The updated SDK aims to solve these problems by implementing support for OAuth 2.0 specification. Implementing support for this protocol means that partners now have opportunity to customise and tailor authorisation experience for their sellers which in many cases improves the seller experience, for example no need for two logins. In addition, SDK sellers will now also be able to authorise/log in with their PayPal accounts .

Get started with Developer Portal

To get started, create a developer account in the Zettle Developer Portal and create an iOS SDK developer application. As part of process, you'll need to provide a callback url (URL Scheme) that needs to be defined in your application's Xcode project. Follow Apple's Defining a Custom URL Scheme for Your App guide to create a callback URL for your application.

After completing the process, you'll be issued a client ID that represents your developer application. Save the issued Client ID and the provided callback URL as they will be needed to initialise the SDK.

Deprecation of API keys

SDK 3.0 deprecates usage of the API keys that were previously required for SDK integrations. Because of this, SDK will no longer need to accept API key as part of the SDK initialisation process.

Required API changes

The new SDK implements breaking API changes as part of the OAuth support and deprecation of API keys. SDK now needs to be intialized with an object that conforms to iZettleSDKAuthorizationProvider protocol. The default implementation of this protocol is implemented by the iZettleSDKAuthorization class that accepts Client ID and callback URL.

Copy
1
- // Initialise the SDK with the API key
2
- iZettleSDK.shared().start(with: "API-KEY")
3
4
+ // Initialise the SDK with authorization provider
5
+ do {
6
+   let authenticationProvider = try iZettleSDKAuthorization(
7
+      clientID: "xxx-xxx-xxx-xxx",
8
+      callbackURL: URL(string: "app-scheme://url"))
9
+   iZettleSDK.shared().start(with: authenticationProvider)
10
+ } catch {
11
+   // Inspect error if any, e.g. callback URL not registered in the Xcode project
12
+   print(error)
13
+ }

iZettleSDKAuthorizationProvider is a new public protocol which can be implemented by partners if they want to improve the authorization experience by e.g. managing Zettle tokens themselves and providing them to the SDK directly. Read more in New Public APIs

New iOS SDK is now distributed as XCFramework bundle which is a new standard way of distributing binary frameworks, released as part of Xcode 11 toolkit. While new format makes manual SDK integration easier, it also enables us to remove the need for stripping unused architectures since that is now natively handled by Xcode. This was previously implemented as part of a "Run Script Phase" and it can be removed after updating to SDK 3.0.

Reduced number of frameworks

Previously, the SDK was distributed as a package of 4 different binary frameworks. This has been reduced to 2 binary XCFrameworks:

• iZettlePayments.xcframework
• iZettleSDK.xcframework

Deprecating Carthage support

Carthage doesn't implement support for binary XCFrameworks Carthage/#2799 which means that Carthage integration won't work with the new Zettle SDK. We advise all partners to use manual integration or Cocoapods instead.

SDK v3.0.0 implements a new public iZettleSDKAuthenticationProvider API to allow integrators to control how authorisation process works. iZettleSDKAuthenticationProvider is a new public protocol, and its definition looks like this:

Copy
1
public typealias iZettleAuthorizationCompletion = (_ tokenData: iZettleSDKOAuthToken?, _ error: Error?) -> Void
2

3
/**
4
 An object conforming to this protocol can be used to authorise the user.
5

6
 The SDK will call each method when neccesary, asking to provide the required information.
7
 When a token is provided the SDK will use it and keep it refreshed it until the user is logged out.
8
 */
9
@objc public protocol iZettleSDKAuthorizationProvider {
10

11
    /// Called to request a token.
12
    ///
13
    /// This method will only be called once when a valid token is requested, the token will be stored internally for subsequent requests.
14
    /// - Parameters:
15
    ///   - completion: Complete with token or error.
16
    @objc func authorizeAccount(completion: @escaping iZettleAuthorizationCompletion)
17

18
    /// Called to request an elevated token.
19
    ///
20
    /// Elevated tokens are stored internally but are not refreshed by the SDK.
21
    /// - Parameters:
22
    ///   - uuid: The uuid of the account performing the operation which requires elevated token.
23
    ///   Use this uuid in the verification step.
24
    ///   - completion: Complete with elevated token or error.
25
    @objc func verifyAccount(uuid: UUID, completion: @escaping iZettleAuthorizationCompletion)
26
}

Integrators can either chose to implement this protocol and specify how authorisation works, or they can use an iZettleSDKAuthentication class that contains the default implementation of this protocol.

iZettleSDKAuthorizationProviderError implements the following error codes.

Copy
1
public let iZettleSDKAuthorizationProviderErrorDomain = NSErrorDomain(string: "com.izettle.sdk.authprovider.error")
2
public enum iZettleSDKAuthorizationProviderError: Int {
3
    case callbackURLInvalid = -202
4
    case callbackURLMissing = -203
5
    case clientIdInvalid = -300
6
    case presentationNotPossible = -501
7
}