cordova-plugin-sms-retriever

License	Platform	Contribute

cordova-plugin-sms-retriever

Cordova plugin to receive verification SMS in Android using the SMS Retriever API.

Installation

Add the plugin with Cordova CLI (v6 or later):

cordova plugin add cordova-plugin-sms-retriever

Add the dependent cordova-support-google-services plugin:

cordova plugin add cordova-support-google-services

Create your project and Android app in Firebase Console, then download the google-services.json file into your platforms/android folder.

Sign your APK with a keystore file if you haven't done it already.

Methods

SMSRetriever.startWatch(successCallback, failureCallback)

Start listening for a single incoming verification SMS. This will later raise the onSMSArrive event when a valid SMS arrives. Example usage:

SMSRetriever.startWatch(function(msg) {
	// Wait for incoming SMS
	console.log(msg);
}, function(err) {
	// Failed to start watching for SMS
	console.error(err);
});

Notice: The API will timeout 5 minutes after starting if no valid SMS has arrived. Also, the API stops listening for SMS after a valid SMS has been detected.

SMSRetriever.getHashString(successCallback, failureCallback)

Get the 11-character hash string for your app using the AppSignatureHelper class.

SMSRetriever.getHashString(function(hash) {
	// Hash string returned OK
	console.log(hash);
}, function(err) {
	// Error retrieving hash string
	console.error(err);
});

Warning: Google advices against dynamically retrieving your hash code before sending the SMS:

Do not use hash strings dynamically computed on the client in your verification messages.

Therefore, do not invoke this method from the published app. The hash is the same for all users, and bound to your keystore signing keys, so you can get it once and never again call the getHashString() method.

Events

onSMSArrive

Triggered when a verification SMS with the proper 11-character hash string has arrived. You need call startWatch() first. Example usage:

document.addEventListener('onSMSArrive', function(args) {
	// SMS arrived, get its contents
	console.info(args.message);
	// To Do: Extract the received one-time code and verify it on your server
});

Construct a verification SMS

The verification SMS message you send to the user must:

Be no longer than 140 bytes
Begin with the prefix <#>
Contain a one-time code that the client sends back to your server to complete the verification flow
End with an 11-character hash string that identifies your app

Otherwise, the contents of the verification message can be whatever you choose. It is helpful to create a message from which you can easily extract the one-time code later on. For example, a valid verification message might look like the following:

<#> 123ABC is your ExampleApp code. FAw9qCX9VSu

Demo App

To test this plugin in a Cordova app using the provided sample:

1. Create a blank cordova app as you regularly do.
2. Install it following the previous instructions.
3. Replace your www folder with the one provided here at the demo folder
4. Start the app in your emulator or device and test the plugin.
5. When you are satisfied, kindly send a donation using the PayPal button on this page.

Screenshots

Here are some screens from the SMSReceiverDemo sample app included in the demo folder. Feel free to try this demo in whatever device you find.

About this Plugin

Prerequisites

This plugin requires the Google Play Services version 10.2 or newer in order to work properly. You must also install the Google Play Services support plugin as explained in the Install section.

Does the plugin work in the Android emulator?

The plugin will work in your emulator as long as you are using a Google Play ABI or System Image, instead of the regular Google APIs ones. This is because these images include the Google Play Store and Google Play Services.

Does the plugin still work with the app minimized?

When the app is sent to the background, as long as Android has not unloaded it to recover memory, SMS watching will remain active and working correctly for 5 minutes.

Does the plugin require SMS permissions?

No, the plugin does not require any kind of permissions because it relies on the SMS Retriever API created by Google.

How this plugin has been tested?

I have tested this plugin with success on:

• Android 5.1.1 emulator
• Android 6.0 emulator
• Android 7.1.1 emulator
• BLU Energy Mini (Android 5.1 Lollipop)
• BLU Vivo 5 Mini (Android 6.0 Marshmallow)
• Samsung Galaxy I9190 (Android 4.4.2 KitKat)

Contributing

Please consider contributing with a small donation using the PayPal button if you like this plugin and it works as expected. No PayPal account is needed.

For support, you may post in the GitHub Issues section. Before reporting that X does not work, please compare the plugin behavior across different devices and emulators in order to locate the exact source of the problem.

How to post Issues

If you are convinced that the plugin needs to be fixed / updated, kindly post your issue in full detail, including Android version, device brand and name, Cordova and cordova-android versions.

Please don't expect me to instantly reply with a magical solution or a new plugin version, but I'll try to help in whatever I can. I'm interested in mantaining this plugin in a working condition, so try to send useful, constructive feedback whenever possible.