SDK

Authentication

This is an add-on feature of the Notificare library. You will need to subscribe to the Users & Authentication add-on and configure this service as described here. With this feature your application can provide creation, authentication and management of user accounts.

In this page we will dive deeper into this functionality. This functionality is built based on the OAuth2 standard, providing your application with the means to create accounts, authenticate users, send email activations, recover and change passwords and refresh access tokens when needed.

First, make sure you declare the following URL Schemes in your app's .plist file:

ios oauth2 url scheme

Make sure you replace {{APP_ID_HERE}} with your app's own ID. You can find the ID in your app's configuration page, as described here.

Then in your AppDelegate.m or AppDelegate.swift make sure your implement the following methods:

//For iOS 9
- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url sourceApplication:(nullable NSString *)sourceApplication annotation:(nonnull id)annotation{
    [[NotificarePushLib shared]  handleOpenURL:url withOptions:nil];

    //Handle your deep linking

    return YES;
}

//Deep Link was executed when your app was inactive in an iOS 9 device
- (void)notificarePushLib:(NotificarePushLib *)library didReceiveLaunchURL:(NSURL *)launchURL {
    [[NotificarePushLib shared]  handleOpenURL:launchURL withOptions:nil];
    //Handle your deep linking
}

//For iOS 10 and higher
-(BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options{
    [[NotificarePushLib shared]  handleOpenURL:url withOptions:options];

    //Handle your deep linking
    return YES;
}
//For iOS 9
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
    NotificarePushLib.shared().handleOpen(url, withOptions: nil)
    //Handle your deep linking
    return true
}

//Deep Link was executed when your app was inactive in an iOS 9 device
func notificarePushLib(_ library: NotificarePushLib, didReceiveLaunch launchURL: URL) {
    NotificarePushLib.shared().handleOpen(launchURL, withOptions: nil)
    //Handle your deep linking
}

//For iOS 10 and higher
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    NotificarePushLib.shared().handleOpen(url, withOptions: options)
    //Handle your deep linking
    return true
}

This allow you to handle the reset password and account activation process after users click validation links from an automated email message.

Create an Account

You are able to create an account by simply invoking the method below and providing three required parameters: email, password and name.

[[[NotificarePushLib shared] authManager] createAccount:@"YOUR_EMAIL" withName:@"A_NAME" andPassword:@"A_PASSWORD" completionHandler:^(id  _Nullable response, NSError * _Nullable error) {
    if (!error) {
        //Account created
    }
}];
NotificarePushLib.shared().authManager().createAccount("YOUR_EMAIL", withName: "A_NAME", andPassword: "A_PASSWORD", completionHandler: {(_ response: Any?, _ error: Error?) -> Void in
    if error == nil {
        //Account created
    }
})

Validate an Account

By default, a newly created account will receive a validation email. This will contain a link to validate the email address. When users click in that email, it will open your app and trigger the following delegate, so please add the following in your AppDelegate.m or AppDelegate.swift:

- (void)notificarePushLib:(NotificarePushLib *)library didReceiveActivationToken:(NSString *)token{

    [[[NotificarePushLib shared] authManager] validateAccount:token completionHandler:^(id  _Nullable response, NSError * _Nullable error) {
        if (!error) {
            //Account validated
        }
    }];

}
func notificarePushLib(_ library: NotificarePushLib, didReceiveActivationToken token: String) {
    NotificarePushLib.shared().authManager().validateAccount(token, completionHandler: {(_ response: Any?, _ error: Error?) -> Void in
        if error == nil {
            //Account validated
        }
    })
}

Recover an Account

Provide your users with a way of requesting a new password when they forget it. You will have to acquire an email address from your user and call the following method:

[[[NotificarePushLib shared] authManager] sendPassword:@"YOUR_EMAIL" completionHandler:^(id  _Nullable response, NSError * _Nullable error) {
    if (!error) {
       //Recover password email sent
    }
}];
NotificarePushLib.shared().authManager().sendPassword("YOUR_EMAIL", completionHandler: {(_ response: Any?, _ error: Error?) -> Void in
    if error == nil {
        //Recover password email sent
    }
})

Upon success, an email with instructions will be sent to your user containing a link that allows the user to complete the password reset process. When users click in that link, your app will open and a token will be passed to your code via the following event:

- (void)notificarePushLib:(NotificarePushLib *)library didReceiveResetPasswordToken:(NSString *)token{
    //Show an UI where user can insert a new password
    //Use the token in that view when creating the new password
}
func notificarePushLib(_ library: NotificarePushLib, didReceiveResetPasswordToken token: String) {
    //Show an UI where user can insert a new password
    //Use the token in that view when creating the new password
}

Keep a reference to that token and build UI to be able to capture the new password. Then, with the token received previously and the new password provided by the user, you can use the following method to complete this operation:

[[[NotificarePushLib shared] authManager] resetPassword:@"NEW_PASSWORD" withToken:token completionHandler:^(id  _Nullable response, NSError * _Nullable error) {
    if (!error) {
        //New password stored, send the user to the login view
    }
}];
NotificarePushLib.shared().authManager().resetPassword("NEW_PASSWORD", withToken: token, completionHandler: {(_ response: Any?, _ error: Error?) -> Void in
    if error == nil {
        //New password stored, send the user to the login view
    }
})

Authenticate an Account

To authenticate the user invoke the following method:

[[[NotificarePushLib shared] authManager] loginWithUsername:@"YOUR_EMAIL" andPassword:@"A_PASSWORD" completionHandler:^(id  _Nullable response, NSError * _Nullable error) {
    if (!error) {
       //User signed in
    }
}];
NotificarePushLib.shared().authManager().login(withUsername: "YOUR_EMAIL", andPassword: "A_PASSWORD", completionHandler: {(_ response: Any?, _ error: Error?) -> Void in
    if error == nil {
        //User signed in
    }
})

User Details

When a user is authenticated, you can easily get their data by calling the following method. On success it will return the user object.

[[[NotificarePushLib shared] authManager] fetchAccountDetails:^(id  _Nullable response, NSError * _Nullable error) {
    if (!error)  {
        //Response will be a NotificareUser object
    }
}];
NotificarePushLib.shared().authManager().fetchAccountDetails({(_ response: Any?, _ error: Error?) -> Void in
    if error == nil {
        //Response will be a NotificareUser object
    }
})

Access Token

At any time after the user is signed in you can generate a access token. This will also create a Push Mail address. Once you generate an access token, you can send push remote notifications to your users via email. Every time this method is invoked a new token/email will be generated.

[[[NotificarePushLib shared] authManager] generateAccessToken:^(id  _Nullable response, NSError * _Nullable error) {
    if (!error) {
        //New token generated successfully
    }
}];
NotificarePushLib.shared().authManager().generateAccessToken({(_ response: Any?, _ error: Error?) -> Void in
    if error == nil {
        //New token generated successfully
    }
})

Change a Password

To provide your authenticated in users with the means to change their password you could build UI that requires the user to insert a new password and then invoke the following method:

[[[NotificarePushLib shared] authManager] changePassword:@"A_NEW_PASSWORD" completionHandler:^(id  _Nullable response, NSError * _Nullable error) {
    if (!error) {
        //Password changed successfully
    }
}];
NotificarePushLib.shared().authManager().changePassword("A_NEW_PASSWORD", completionHandler: {(_ response: Any?, _ error: Error?) -> Void in
    if error == nil {
        //Password changed successfully
    }
})

Sign out

To logout the user invoke the following method:

[[[NotificarePushLib shared] authManager] logoutAccount:^(id  _Nullable response, NSError * _Nullable error) {
 //Show the login form or any other un-authenticated view
}];
NotificarePushLib.shared().authManager().logoutAccount({(_ response: Any?, _ error: Error?) -> Void in
 //Show the login form or any other un-authenticated view
})

Handling Errors

All the HTTP errors that our library returns under the form of a NSError object, can be translated like shown below:

switch ([error code]) {
    case kNotificareErrorCodeBadRequest:
    case kNotificareErrorCodeUnauthorized:
    case kNotificareErrorCodeNotFound:
    case kNotificareErrorCodeConflict:
    case kNotificareErrorCodeUnprocessableEntity:
    case kNotificareErrorCodeInternalServerError:
    case kNotificareErrorCodeGatewayTimeout:
        break;
    default:
        break;
}
switch error?.code {
    case kNotificareErrorCodeBadRequest, kNotificareErrorCodeUnauthorized, kNotificareErrorCodeNotFound, kNotificareErrorCodeConflict, kNotificareErrorCodeUnprocessableEntity, kNotificareErrorCodeInternalServerError, kNotificareErrorCodeGatewayTimeout:
        break
    default:
        break
}