SchibstedAccount iOS SDK

The SchibstedAccount iOS SDK provides you access to Schibsted identity services via the SPiD APIs. It provides the following:

• User management (profiles, logins, signups)
• UI based logins
• Authenticated request and oauth management

Note: The APIs provided by the SDK do not cover the full spectrum of APIs provided by SPiD. If there is functionality missing, please look at the SPiD API reference and open up an issue for an enhancement request.

• Documentation: Here's the documentation to the latest tagged release (which can be different than the version that's in master).
• Contributing: For details on getting up and running if you are thinking of contributing

Setup

CocoaPods

The pod is available as a public cocoapod under the name SchibstedAccount

The SDK is divided in to different subspecs:

• pod 'SchibstedAccount': this is the default and contains APIs to create a User
• pod 'SchibstedAccount/Manager': the default installs the entire SDK. If you want to only use headless login (i.e. no UI libraries included), then just use this.

You may want to include a tracking subspec as well

The UI does some internal tracking, and allows a TrackingEventsHandler to be set in the UI's configuration. To fulfill this, you can either implement it yourself or use one which is already implemented.

Internal: There is an internal Schibsted Tracking implementation for the identity SDK availabe here and is available from source "git@github.schibsted.io:CocoaPods/Specs.git, so in your pod file you may:

• pod 'SchibstedIDTracking': Adds dependency to the new pulse SDK

Carthage

Add this to your Cartfile

git "git@github.com:schibsted/account-sdk-ios.git"

Then run:

$ carthage bootstrap --platform ios

or

$ carthage update --platform ios

Internal: And, if you also want to include support for tracking events in the identity UI with the new pulse SDK, add this

git "git@github.schibsted.io:spt-identity/identity-sdk-ios-tracking"

Carthage will build the frameworks you need to link in your project, so make sure you follow these steps to include all of them in your project and you should be up and running. If there is something missing -> email us.

Get some client credentials

The SDK works by giving you access to Schibsted users. And what kind of access is allowed is determined by a set of client credentials. The first thing you must do is get some credentials, which can be done through self service. Learn about environments and merchants.

NOTE: The SDK will not work across environments or merchants.

Usage

The most common use case is to get a hold of a User object. You can obtain a User object by using a visual or a headless login process. The visual login is the recommended approach, but if the need arises the headless approach is also documented, but not "officially" supported.

Set your client configuration

See above for getting credentials. But once you have them you have to set up a ClientConfiguration object:

extension SchibstedAccount.ClientConfiguration {
    static let `default` = ClientConfiguration(
        environment: .preproduction,
        clientID: "<your-client-code>",
        clientSecret: "<your-client-secret>",
        appURLScheme: nil
    )
}

All these fields must be retrieved from the selfservice portal. If you set appURLScheme to nil then the SDK assumes the defult scheme which is spid-<your-client-code>. Please double check that this is the same as the default scheme as listed in your Redirect URI tab in self service.

Check if you already have a user

Get the last user that was logged in with the SDK

let user = User.loadLast(clientConfiguration: .default);
user.delegate = //...
switch user.state {
case .loggedIn:
    // Yay, carry on with app
case .loggedOut:
    // Ok, fire up the IdentityUI
}

Even if there was no user persisted to the keychain, this function will return an initialized user object. Checking the state of the user tells you if the keychain data "looks" valid.

Note: however that the data may have expired even though it is in the keychain, in which case the SDK will try and refresh it automatically for you if you make any requests using the provided extension on URLSession.

Visual login with IdentityUI

To start the login process you can fire up an IdentityUI object with an IdentityUIConfiguration (this is different than the ClientConfiguration) and it will create a User object for you if everything goes right. It is recommended to use the IdentityUI to create a User object because it makes sure that the correct login flows supported by the Schibsted Identity backend are adhered to (ie: required fields are filled in, and terms and conditions are accepted, etc).

Logging in with the IdentityUI

import UIKit
import SchibstedAccount

extension IdentityUIConfiguration {
    // See docs for more options
    static let `default` = IdentityUIConfiguration(
        clientConfiguration: .default,
        isCancelable: true,
        isSkippable: true
    )
}

class ViewController: UIViewController {

    var identityUI: IdentityUI?
    var user: User?

    @IBAction func didTapLoginButton(_ sender: UIButton) {
        let identifierType: IdentifierType = (sender.tag == 0) ? .phone : .email
        self.identityUI = IdentityUI(configuration: .default, identifierType: identifierType)
        self.identityUI?.delegate = //...
        self.identityUI?.presentIdentityProcess(from: self)
    }

    @IBAction func didTapLogoutButton(_: Any) {
        self.user?.logout()
        print("User logout done!")
    }
}

To handle the login/signup/error/or any other supported events you can set the IDentityUIDelegate.

IdentityUIDelegate and UserDelegate

extension ViewController: IdentityUIDelegate {
    func didFinish(result: IdentityUIResult) {
        switch result {
        case .canceled:
            print("The user canceled the login process")
        case let .completed(user):
            self.user = user
            self.user.delegate = //...
            print("User with id \(String(describing: user.id)) is logged in")
        // ... see docs for more cases
        }
    }
}

extension ViewController: UserDelegate {
    func user(_: User, didChangeStateTo newState: UserState) {
        switch newState {
        case .loggedIn:
            print("The user logged in")
        case .loggedOut:
            print("The user logged out")
        }
    }
}

UI Customization

The SDK includes an IdentityUITheme object that allows you to customize the look and feel of the identity UI. See the docs for, hopefully, more details.

Localization

The SDK comes with the following localization support:

1. 🇳🇴 Norwegian Bokmål
2. 🇸🇪 Swedish
3. 🇫🇮 Finnish

Touch ID

Starting from version 2.1.0 of the SDK, and after a first successful password authentication, users can enroll their Touch ID to later use it in a place of entering their password. It is also strongly recommended that users should be able to disable/enable authentication using Touch ID at any time, for which you need to add a UI component (typically a UISwitch) to your app settings which calls IdentityUIConfiguration.useBiometrics.

Headless login with IdentityManager

Note: It is recommended to use the UI approach.

The IdentityManager is more bare bones and doesn't ensure any kind of Schibsted identity flows. It can create a user object and also notify you of any changes that happen to the user object. You can assign an IdentityManagerDelegate to it to handle various events that take place:

import SchibstedAccount

class ViewController: UIViewController, IdentityManagerDelegate {
    let identityManagaer = SchibstedAccount.IdentityManager(clientConfiguration: clientConfiguration)

    override func viewDidLoad() {
        super.viewDidLoad()
        self.identityManager.delegate = self
        if self.identityManager.currentUser.state == .loggedIn {
            // User is already logged in
            return
        }

        // User not logged in
        self.login()
    }

    func userStateChanged(_ state: UserState) {
        // User has just logged in or just logged out
        if state == .LoggedIn {
            print("User with id \(String(describing: self.identityManager.currentUser.id)) is logged in")
        }
    }

    func login() {
        self.identityManager.sendCode(to: PhoneNumber(...) ...) { result in
            if case .failure(let error) = result {
                print("failed to send code", error)
            }
        }
    }

    @IBAction func validateCode(_ sender: UIButton) {
        let code = self.codeTextField.text
        identityManager.validate(oneTimeCode: code, for: PhoneNumber(...) ...) {

        }
    }
}

Building, testing, documentaion

See contributing.md.