Android Quickstart

This Quickstart demonstrates how to send Push Notifications using Notify and a Twilio Notify sample Android app.

NOTE
In this guide we will use FCM (Firebase Cloud Messaging) as a messaging service to send Android Push Notifications. To configure FCM notifications for this Quickstart (if not configured already) follow this guide.

In the console, create a Notify service. Make note of the SID! You will use this later when you start writing code further down.

Notify SMS Quickstart - set up Notify Service Instance

Gather account information


We need to do is grab all the necessary information from our Twilio account. Here's what we'll need

Config Value Description
Service Instance SID A service instance where all the data for our application is stored and scoped. You can create one in the console.
Account SID Used to authenticate REST API requests - find it in the console here.
API Key Used to authenticate REST API requests - like the Account SID, find it in the console here.
API Secret Used to authenticate REST API requests - like the Account SID, find it in the console here.

You will also need to create a push credential on the Twilio Console, and then configure it on your Notify service. You can upload your credentials here. If you do not yet have one, you can provision one following this guide.

NOTE
Make sure that you set the package name to com.twilio.notify.quickstart when you register the app in the Firebase console to match the application package name of the Android quickstart app.

Set up the server app


When using the Notify service, you'll need to be able to register devices to receive notifications, and then send notifications to those devices. To get you going quickly, we've created a server that accomplishes these tasks in:

The sample mobile app is set up to communicate with the server-side app to register a device for notifications. More on this in the next paragraphs.

For this example let's use the Node.js server, but you can pick the language you prefer.

Next you will need to :
  • Step 1: Install Node.js (if you don't have it already)
  • Step 2: Download Node.js server app and unzip it
  • Step 3: Configure and run the server app on your machine

Step 1: Install Node.js

Get Node.js here and complete the installation.

Step 3: Configure and run the server app on your machine

Now that you have Node.js installed and the Node.js server downloaded and unpacked, it is time to configure the server with your specific account information. Copy the .env.example file to .env. Next, we need to edit the .env file to include the three configuration parameters (Account SID, Auth SID, Notify Service instance SID) we gathered from above. You can do this from the Terminal window on your Mac or with any text editor.

Loading Code Samples...
Language
{
  "type": "server",
  "description": "Sample configuration files for Notufy",
  "title": "Notify Environment Configuration"
}
# Required for all uses
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=xxxxxxxxxxxxxxxxxxxxx

# Required for Video
TWILIO_CONFIGURATION_SID=

# Required for Chat
TWILIO_CHAT_SERVICE_SID=

# Required for Notify
TWILIO_NOTIFICATION_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxx

# Required for Sync
TWILIO_SYNC_SERVICE_SID=
# Required for all uses
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=xxxxxxxxxxxxxxxxxxxxx

# Required for Video
TWILIO_CONFIGURATION_SID=

# Required for Chat
TWILIO_CHAT_SERVICE_SID=

# Required for Notify
TWILIO_NOTIFICATION_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxx

# Required for Sync
TWILIO_SYNC_SERVICE_SID=
Sample configuration files for Notufy
Notify Environment Configuration

Sample configuration files for Notufy

Now we'll want to install our dependencies. In your Terminal window, navigate to the folder, where you unzipped the app, and run:

npm install

Once we've done configuring we're ready to start the server - again in your terminal, run:

npm start

To confirm the server is running, visit http://localhost:3000 in a web browser. You should see the home screen, informing you of which services have been configured.

Twilio SDK Starter Home Screen

 

 

Now that our server is set up, let's get the Twilio Notify sample Android app up and running.

Set up the Twilio Notify sample Android app


Next we need to:
  • Step 1: Get the Twilio Notify sample Android app
  • Step 2: Configure Android Push Notifications, if not done yet
  • Step 3: Run Twilio Notify sample Android app

To get going quickly, we provide an Android sample app built as a stand-alone Android Studio project written in Java:

The application is built using the Gradle automation system and is available on GitHub.

Open Android Studio and import the project by double clicking on it's build.gradle file.

If not done yet, follow this guide to configure Android Push Notifications for the Twilio Notify sample Android app.

NOTE
Use the following values for the sample app:
  • App name: Notify Quickstart
  • Android package name: com.twilio.notify.quickstart

 Next, go to Firebase Console to generate a 'google-services.json' file for your app.

Open your project

Firebase Notify Quickstart

     

Go to the settings 

Firebase Notify Quickstart Settings

 

Download google-services.json file and save it to the /app folder. This file configures your app to receive notifications via FCM. 

Firebase Download google-services.json 

Compile the project and it will build your gradle dependencies automatically.

Next, in the notifyapi/TwilioSDKStarterAPI.java file on this line: private final static String BASE_SERVER_URL = "YOUR_SDK_STARTER_SERVER_URL"; replace the string with the address of your server.

 

Notify Quickstart Base Server URL



Create a Binding for Android Push Notifications (FCM)


Next we need to create a Binding between user Identity and the device running the app. User Identity can be any unique identifier you choose, like GUID. You can find out more about Identity and Bindings in the Binding resource reference API

In the app enter Identity you choose and click the button Create binding.

 

Notify Android Quickstart - Sample mobile app creating a binding

 

This action creates a Binding which uniquely identifies a user on a certain device, running your application.

In the terminal window running Node.js server, you should see something like this

BindingInstance {
  _version: 
   V1 {
     _domain: 
      Notify {
        twilio: [Object],
        baseUrl: 'https://notify.twilio.com',
        _v1: [Circular] },
     _version: 'v1',
     _credentials: undefined,
     _services: 
      { [Function: ServiceListInstance]
        _version: [Circular],
        _solution: {},
        _uri: '/Services',
        create: [Function: create],
        each: [Function: each],
        list: [Function: list],
        page: [Function: page],
        get: [Function: get] } },
  sid: 'BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  accountSid: 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX,
  serviceSid: 'ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX,
  dateCreated: 2017-01-17T13:07:39.000Z,
  dateUpdated: 2017-01-17T13:07:39.000Z,
  notificationProtocolVersion: '3',
  endpoint: 'user9999999XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  identity: 'user9999999',
  bindingType: 'fcm',
  address: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  tags: [],
  url: 'https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings/BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  _context: undefined,
  _solution: 
   { serviceSid: 'ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
     sid: 'BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' } }

If you are running the sample app in debugger mode and it wasn't successful, you'll see an error message printed in the console.

Do not use Personally Identifiable Information for Identity
Notify uses Identity as a unique identifier of a user. You should not use directly identifying information (aka personally identifiable information or PII) like a person's name, home address, email or phone number, etc., as Identity because the systems that will process this attribute assume it is not directly identifying information.

Now that we have the Binding, we are ready to send a Push Notification to an Android app running on a device or on the emulator.

Send a Push Notification to your App


To send a notification, you can use the Notify page on the server starter kit you downloaded. Just go ahead and click the Notify button at the bottom of the home page to go to the Notify page.

On this page, send a message to the identity you used in the app. Because you registered a binding with Twilio, the server will send your device the 'Hello IDENTITY' message as a notification.

You're all set! From here, you can start building your own application.

Running Twilio Notify sample Android app on a device with ngrok


NOTE
To send Push Notifications to a device, we need to run the Twilio Notify sample Android app on the device and expose the Node.js local server public URL

One of the ways to do that is to use ngrok.

Download ngrok. Navigate to ngrok folder in Terminal window and run:

./ngrok http 3000

as a result you should see something like this

Session Status                online                                                                                                            
Version                       2.1.18                                                                                                            
Region                        United States (us)                                                                                                
Web Interface                 http://127.0.0.1:4040                                                                                             
Forwarding                    http://a9534ff6.ngrok.io -> localhost:3000                                                                        
Forwarding                    https://a9534ff6.ngrok.io -> localhost:3000                                                                       

Connections                   ttl     opn     rt1     rt5     p50     p90                                                                       
                              2       0       0.00    0.00    61.71   120.52                                                                                                                                                                           

Next, in the notifyapi/TwilioSDKStarterAPI.java file on this line: private final static String BASE_SERVER_URL = "YOUR_SDK_STARTER_SERVER_URL"; replace the string with the address of your server.

 

Notify Quickstart Base Server URL

 

Now build the app to your device. When the app loads, you should see a simple UI where you can enter an identity for the user and send a Push notification to the device, exactly as on the Simulator

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

1 / 1
Loading Code Samples...
{
  "type": "server",
  "description": "Sample configuration files for Notufy",
  "title": "Notify Environment Configuration"
}
# Required for all uses
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=xxxxxxxxxxxxxxxxxxxxx

# Required for Video
TWILIO_CONFIGURATION_SID=

# Required for Chat
TWILIO_CHAT_SERVICE_SID=

# Required for Notify
TWILIO_NOTIFICATION_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxx

# Required for Sync
TWILIO_SYNC_SERVICE_SID=
# Required for all uses
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=xxxxxxxxxxxxxxxxxxxxx

# Required for Video
TWILIO_CONFIGURATION_SID=

# Required for Chat
TWILIO_CHAT_SERVICE_SID=

# Required for Notify
TWILIO_NOTIFICATION_SERVICE_SID=ISxxxxxxxxxxxxxxxxxxxxxxx

# Required for Sync
TWILIO_SYNC_SERVICE_SID=