iOS Quickstart

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

NOTE
To complete this guide you will need to have Apple developer account, run Xcode on your machine and have iOS Push Notifications configured.

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.

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 something similar to this home screen:

Twilio SDK Starter Home Screen

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

 

Set up the Twilio Notify sample iOS app


Next you will need to :
  • Step 1: Get the Twilio Notify sample iOS app
  • Step 2: Configure iOS Push Notifications, if not done yet
  • Step 3: Run Node.js server app and expose public server URL
  • Step 4: Step 4: Run Twilio Notify sample iOS app on a device and have it pointing to the public server URL

Step 1: Get the Twilio Notify sample iOS app

We've provided sample applications to help you get running quickly in both Objective-C and Swift.

Download and unzip the version you prefer, and then open it in XCode:

These applications are available on GitHub (Objective-C, Swift).

Step 2: Configure iOS Push Notifications

If not done yet, follow this guide to configure iOS Push Notifications.

Next, open the notification project's configuration. On the General tab, set the Bundle Identifier to match the one you used to generate the certificate while configuring iOS Push Notifications.

Notify iOS Quickstart - Sample mobile app bundle identifier

Step 3: Run Node.js server app and expose public server URL

NOTE
To be able to send Push Notifications, we need to run the Twilio Notify sample iOS app on the device, as Push Notifications do not work on the iOS Simulator.

In this example, to expose our local server to public and enable mobile app to communicate with it, we will 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                                                                                                                                                                           

Step 4: Run Mobile app on a device and have it pointing to the public server URL

To have the mobile app, running on your device, talking to the Node.js server, replace the URL at the top of the ViewController file with a public URL, forwarded to our local Node.js server with ngrok (here http://a9534ff6.ngrok.io). Check out ngrok "Getting Started" guide for more details.

Notify iOS Quickstart - Sample mobile app pointing to public 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.

Next we can create a Binding between user Identity and this device.

Create a Binding for iOS Push Notifications (APNS)


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.

In the app enter Identity you choose and click the button Register.

Notify iOS 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: 'user999999999XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  identity: 'user999999999',
  bindingType: 'apn',
  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 our first Push Notification with Notify.

Send a Push Notification to device running Twilio Notify sample iOS 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 World!' message as a notification.

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

What's next?


There's much more you can do with Notify. Try our other Quickstarts to send:

Or learn how to:

For more information on the Notify API, check out our REST API docs.

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=