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 AndroidManifest.xml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<activity
  android:name=".MainActivity"
  android:label="@string/app_name"
  android:launchMode="singleTop"
  android:configChanges="keyboard|keyboardHidden|orientation|screenSize">

  // ... more

  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:host="${notificareHost}"
      android:pathPrefix="/oauth/resetpassword/${notificareAppId}"
      android:scheme="https" />
  </intent-filter>
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:host="${notificareHost}"
      android:pathPrefix="/oauth/validate/${notificareAppId}"
      android:scheme="https" />
  </intent-filter>
</activity>

Make sure you replace ${notificareAppId} with your app's own ID, e.g., by including it in your build.gradle as a build variable. You can find the ID in your app's configuration page, as described here.

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, name and password.

1
await notificare.createAccount(email, name, password);

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 event which you should use to validate the account:

1
2
3
4
5
6
7
8
9
10
notificare.onEventReceived.listen((NotificareEvent event) async {
  if (event.name == "activationTokenReceived") {
    try {
      await notificare.validateAccount(event.body.token);
      //Handle Success
    } catch(e){
      //Handle Error
    }
  }
});

Recover an Account

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

1
2
3
4
5
6
try {
  await notificare.sendPassword(email);
  //Handle Success
} catch(e){
  //Handle Error
}

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 a user clicks in that link, your app will open and a token will be passed to your code via the following event:

1
2
3
4
5
notificare.onEventReceived.listen((NotificareEvent event) {
  if (event.name == "resetPasswordTokenReceived") {
    //Keep a reference of the event.body.token
  }
});

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:

1
2
3
4
5
6
try {
  await notificare.resetPassword(password, token);
  //Handle Success
} catch(e){
  //Handle Error
}

After this point, you user will be able to sign in using the new password.

Authenticate an Account

To authenticate the user invoke the following method:

1
2
3
4
5
6
try {
  await notificare.login(email, password);
  //Handle Success
} catch(e){
  //Handle Error
}

Whenever an account changes state or when your app launches the following delegate will be triggered:

1
2
3
4
5
notificare.onEventReceived.listen((NotificareEvent event) {
  if (event.name == "accountStateChanged") {

  }
});

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 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:

1
2
3
4
5
notificare.onEventReceived.listen((NotificareEvent event) {
  if (event.name == "accountSessionFailedToRenewWithError") {
    //Handle revoke or expired session. You might want to show the login screen in response to this event
  }
});

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.

1
2
3
4
5
6
try {
  NotificareUser user = await notificare.fetchAccountDetails();
  //Handle Success
} catch(e){
  //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 via email. Every time this method is invoked a new token/email will be generated.

1
2
3
4
5
6
try {
  NotificareUser user = await notificare.generateAccessToken();
  //Handle Success
} catch(e){
  //Handle Error
}

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:

1
2
3
4
5
6
try {
  await notificare.changePassword(password);
  //Handle Success
} catch(e){
  //Handle Error
}

Sign out

To end a user session invoke the following method:

1
2
3
4
5
6
try {
  await notificare.logout();
  //Handle Success
} catch(e){
  //Handle Error
}