Authentication

If you want your users to be able to upload content or other operations you'll need them to login with their Newzulu Platform account. The SDK comes with an handy login API to help you do it.

Authenticating the user

To authenticate a user, they'll need to input their email and password.

Here's how to pass them to the SDK:

let email = "user@example.com"
let password = "*****"
let sessionStore = KeychainStore(identifier: "MyApplication")
platformClient.setCredentials(email: email, password: password, sessionStore: sessionStore)

The KeychainStore is a storage for the SDK that allows the user session to persist in the keychain across application launches, thus saving the cost to authenticate again. If you don't want the session to persist, you can use the default sessionStore parameter (i.e. EphemeralSessionStore()). On the other hand, if you want to also persist the credentials, the KeychainStore object provides methods for storing and retrieving passwords from the keychain.

Calling setCredentials(email:password:userVHost:sessionStore) won't authenticate your user directly. If you want to make sure the credentials are valid, you then need to invoke the authenticate(onSuccess:onError:) method to validate the credentials with the server and create a new session:

platformClient.authenticate(onSuccess: { session in
    // User is authenticated and now has a valid session.
    // You can use APIs that require authentication.
}, onError: { error in
    // An error occurred during authentication.
    // See “Handling errors” below.
})

If you're confident that the credentials are valid (e.g. the application has already authenticated with the same credentials in the past), you may skip the authentication process. It will be performed automatically as needed when you perform a request.

Accessing user information

If the login was successful you can access the user information via the Session object.

You can retrieve the session in the onSuccess completion block you pass to the authenticate(onSuccess:onError:) method or you can access it later with the currentSession property of your PlatformClient.

This session object contains a User object:

if let user = platformClient.currentSession?.user {
    // Use the user information
}

Note that currentSession is nil when the user isn't properly authenticated.

The user object contains the following information:

  • id: The unique ID of the user on the server.
  • username: The username.
  • firstName and lastName: The first and last name of the user (optional).
  • email: The email address of the user (optional).

Handling errors

If the login fails, a NewzuluError is passed to the onError block, which contains information about what went wrong. The error has a reason property that can be one of the following cases:

  • .networkFailure: A network error occurred and the SDK unable to reach the remote server.
  • .wrongCredentials: The provided email and/or password aren't correct.
  • .serverFailure: The remote server encountered an error, you should try again later.
  • .invalidRepresentation: The response from the remote server cannot be understood.
  • .unknown: An unknown internal error occurred.

As NewzuluError is declared in the Newzulu Core framework, you need to import NewzuluCore in your source file when dealing with errors.