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 and lower
-(BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options{
    [[NotificarePushLib shared]  handleOpenURL:url];

    //Handle your deep linking

    return YES;
}


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

    //Handle your deep linking
    return YES;
}

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

//For iOS 10 and higher
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    NotificarePushLib.shared().handleOpen(url)
    //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] createAccount:@"EMAIL" withName:@"NAME" andPassword:@"PASSWORD" completionHandler:^(NSDictionary *info) {

  //Handle Success

} errorHandler:^(NSError *error) {

  //Handle Error
}];

NotificarePushLib.shared().createAccount("EMAIL", withName: "NAME", andPassword: "PASSWORD", completionHandler: {(_ info: [AnyHashable: Any]) -> Void in
    //Handle Success
}, errorHandler: {(_ error: Error?) -> Void in
    //Handle Error
})

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] validateAccount:token completionHandler:^(NSDictionary *info) {

      //Handle Success

    } errorHandler:^(NSError *error) {

      //Handle Error
    }];
}

func notificarePushLib(_ library: NotificarePushLib, didReceiveActivationToken token: String) {
    NotificarePushLib.shared().validateAccount(token, completionHandler: {(_ info: [AnyHashable: Any]) -> Void in
        //Handle Success
    }, errorHandler: {(_ error: Error?) -> Void in
        //Handle Error
    })
}

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. Upon success, an email with instructions will be sent to your user.

[[NotificarePushLib shared] sendPassword:@"EMAIL" completionHandler:^(NSDictionary *info) {

  //Handle Success

} errorHandler:^(NSError *error) {

  //Handle Error
}];

NotificarePushLib.shared().sendPassword("EMAIL", completionHandler: {(_ info: [AnyHashable: Any]) -> Void in
    //Handle Success
}, errorHandler: {(_ error: Error?) -> Void in
    //Handle Error
})

Reset a Password

Provide your users with a way of changing their password upon request. This method will required both a new password and the token received in the email. If a user clicks in the link in that email, it will open your app and trigger the following delegate, please implement it in your AppDelegate.m or AppDelegate.swift:

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

    //Show UI to allow the user to reset password, store token for later
}

func notificarePushLib(_ library: NotificarePushLib, didReceiveResetPasswordToken token: String) {
    //Show UI to allow the user to reset password, store token for later
}

This should trigger UI asking the user to insert a new password. The token received must be then used in the following method:

[[NotificarePushLib shared] resetPassword:@"NEW_PASSWORD" withToken:token completionHandler:^(NSDictionary *info) {

    //Handle Success

} errorHandler:^(NSError *error) {

    //Handle Error
}];

NotificarePushLib.shared().resetPassword("NEW_PASSWORD", with: token, completionHandler: {(_ info: [AnyHashable: Any]) -> Void in
    //Handle Success
}, errorHandler: {(_ error: Error?) -> Void in
    //Handle Error
})

Authenticate an Account

To authenticate the user invoke the following method:

[[NotificarePushLib shared] loginWithUsername:@"EMAIL" andPassword:@"PASSWORD" completionHandler:^(NSDictionary *info) {

  //Handle Success

} errorHandler:^(NSError *error) {

  //Handle Error
}];

NotificarePushLib.shared().login(withUsername: "EMAIL", andPassword: "PASSWORD", completionHandler: {(_ info: [AnyHashable: Any]) -> Void in
    //Handle Success
}, errorHandler: {(_ error: Error?) -> Void in
    //Handle Error
})

If authentication is successful it will trigger the following delegate:

- (void)notificarePushLib:(NotificarePushLib *)library didChangeAccountNotification:(NSDictionary *)info{

    //User is authenticated

}

func notificarePushLib(_ library: NotificarePushLib, didChangeAccountNotification info: [AnyHashable: Any]) {
    //User is authenticated
}

When this delegate is triggered we will automatically register the device to the authenticated user profile. After this point you can also start safely invoking all the methods that available for authenticated users.

If authentication fails or the user session is for some reason terminated, you should use the following delegate to handle your app's UI accordingly:

- (void)notificarePushLib:(NotificarePushLib *)library didFailToRequestAccessNotification:(NSError *)error{

  //Whenever this event occurs you should update your UI to show the sign in view
  //This will happen when you call logout or your authentication process failed

}

func notificarePushLib(_ library: NotificarePushLib, didFailToRequestAccessNotification error: Error?) {
    //Whenever this event occurs you should update your UI to show the sign in view
    //This will happen when you call logout or your authentication process failed
}

User Details

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

[[NotificarePushLib shared] fetchAccountDetails:^(NSDictionary *info) {

  //Handle Success

} errorHandler:^(NSError *error) {

  //Handle Error
}];

NotificarePushLib.shared().fetchAccountDetails({(_ info: [AnyHashable: Any]) -> Void in
    //Handle Success
}, errorHandler: {(_ error: Error?) -> Void in
    //Handle Error
})

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 using an email message. Every time this method is invoked a new token/email will be generated.

[[NotificarePushLib shared] generateAccessToken:^(NSDictionary *info) {

  //Handle Success

} errorHandler:^(NSError *error) {

  //Handle Error
}];

NotificarePushLib.shared().generateAccessToken({(_ info: [AnyHashable: Any]) -> Void in
    //Handle Success
}, errorHandler: {(_ error: Error?) -> Void in
    //Handle Error
})

Change a Password

To provide your signed in users with the means to change their password you can easily invoke the following method.

[[NotificarePushLib shared] changePassword:@"PASSWORD" completionHandler:^(NSDictionary *info) {

  //Handle Success

} errorHandler:^(NSError *error) {

  //Handle Error
}];

NotificarePushLib.shared().changePassword("PASSWORD", completionHandler: {(_ info: [AnyHashable: Any]) -> Void in
    //Handle Success
}, errorHandler: {(_ error: Error?) -> Void in
    //Handle Error
})

Sign out

To logout the user invoke the following method:

[[NotificarePushLib shared] logoutAccount];

NotificarePushLib.shared().logoutAccount()

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
}

SDK