Exosite provides the ability to use activation and password reset emails in conjunction with a mobile app. In order to setup this feature, you must have admin privileges to your Portals IoT solution. In order to make full use of this, you must also have a mobile app with a registered URL scheme.
To setup your solution to use Mobile URLs you will first have to visit your moderation page at: <solution>.<vendor>.com/admin/moderate. E.G. https://example.exosite.com/admin/moderate. You must ensure that the 'Moderate New User Signup' is set to 'Off'. If the setting is 'Off' already, you need only click the off radio button and then click the 'Submit' button. If this is done properly it will look like this:
The next step if to visit your solution's plan page: <solution>.<vendor>.com/admin/plans. Here you will check that users will automatically have a portal with a plan of your choice created for them. Please check the last option in 'Signup and Account Page Configuration' and select your desired portal plan for your customers. This screenshot of an example solution that automatically creates portals for users with the 'community' plan(1 User, 2 Devices):
The last step in solution configuration is to visit your page at: <solution>.<vendor>.com/admin/configuration, and scroll down the page until you find the form with header “Customer URL Scheme”. Here you must type in the registered URL scheme of your mobile application. After you ensure your app's URL scheme is spelled correctly -- press submit. Your Portals IoT solution’s activation and password reset emails will now open the specified mobile application. Here is an example of what this setup would look like using a placeholder app scheme:
You can test this out very quickly on an iPhone:
- Enter “videos" into the Customer URL Scheme form.
- Create a new user with unique email address that you have access to, either through the web interface or Portals API.
- Through your phone, open the mailbox of the new user and find the newly sent activation email.
- Click on the activation link.
- First your default mobile browser will launch.
- You will then find that the link will open your "Videos" app.
If you choose to customize the activation and password-reset emails for your solution, you must ensure that you still include the application replaceable text. For example without '[automatic activation url]', your email will not contain the activation URL for your customer to click on. See the Screenshot below for example email templates and all replaceable text references:
Remember that the activation link sent to your user will always look like the following scheme: https://<solution>.<vendor>.com/activate?key=<value>. This means that when the activation link is pressed, it will take the phone's browser to the portals application. The Exosite platform will then redirect the user’s mobile browser to open the custom application. If this is done correctly, your mobile application will be restarted with something similar to the following example URL passed to it, myApp://activate?key=c80737a9527bf81982fb6d6a56cbb506dc5bdedd. Below are real activation and password reset emails using the above templates and the app URL scheme:
If you are unclear about what your apps registered URL scheme is, you may check this within your development environment. The android scheme is defined within your application's AndroidManifest.xml file. Specifically as a data element. E.G. <data android:scheme="myApp">. For iOS the URL scheme can be found in your project info.plist as a property called URL Scheme.
Additionally you will need to pass in the activation token, and other parameters into your application. This is different with each mobile operating system. In Android you will have to setup a couple of intent filters in order to handle the activation and password reset tokens. You can later call getIntent() in order to retrieve the intent object that started your activity.
For iOS you will have to handle the web-application passed tokens inside of your mobile app delegate. This is often accessed by the URL's query string.
You may also find the following development guides useful (unaffiliated with Exosite):
- Android Guide: http://developer.android.com/training/basics/intents/filters.html#HandleIntent
- iOS Guide: http://iosdevelopertips.com/cocoa/launching-your-own-application-via-a-custom-url-scheme.html
Conclusion: The Standard Mobile Sign-up Flow
|#||End User View||Application View|
|1||Launch mobile app, click on 'Sign Up' button||Go to SIGN UP page with registration form|
|2||Enter valid email, and press 'Submit' button||Use the entered email and call Create User API with X-User-Agent header set to the user-provided email address.|
|3||The app shows a message: "Success! Please check your email for activation code."||Show success message or Error Handling|
|4||Opens mailbox, opens unread email from your IoT solution and sees activation link + temporary password||Other mobile app in use -|
|5||Clicks on activation link, and then the phone's default mobile browser launches||Mobile browser in use-|
|6||The URL resolves inside the mobile browser and user is brought back to the mobile app.||Browser redirects to app; if iOS read the 'query string' for the activation token, if Android read the intent object's data for the activation token. Then the app must call Account Activation API with the passed activation key.|
|7||The app shows a message: "Registration successful! Please login with the provided temporary password."||Show success message or Error Handling|
|8||User logs-in with temporary password|
It is very important that while making the Create User API call that you include the X-User-Agent header with the value of the mobile user's email. This is the address that the platform will send activation email to.
With all settings in the platform configured properly and your app ready to handle the mobile URL and the activation key, you have successfully completed implementing the use of mobile URLs with Exosite.