Getting Started with Node.js

Introduction

This tutorial will have you deploying a Node.js app for use on SMS and Web channels in minutes.

The tutorial assumes that you have a free or paid ONEm account, and that you have the following prerequisites installed locally:

Set up on localhost

To start with, we will be running all commands locally on your own PC. Your app will initially be hosted there for local development, then later you will learn how to host your app using a cloud provider such as Heroku for use on production.

Before you continue, check that you have the prerequisites installed properly. Type each command below and make sure it displays the version you have installed. Your versions might differ from the example. If an error is returned, go back check the installation before continuing.

This tutorial will work for any version of Node greater than 8 - check that it’s there:

1
2
$ node --version
v10.15.3

npm is installed with Node, so check that it’s there. If you don’t have it, install a more recent version of Node:

1
2
$ npm --version
6.9.0
Now check that you have git installed:

1
2
$ git --version
git version 2.15.1

We will use ngrok to provide a secure tunnel between your app running on localhost and the ONEm servers. Check it's installed:

1
2
$ ./ngrok --version
ngrok version 2.3.29

Prepare the app

In this step, you will prepare a simple Hello World application. To clone a local version of the sample application, execute the following command in your local command shell or terminal:

1
$ git clone https://github.com/onem-developer/hello-world-node-js.git && cd hello-world-node-js

You now have a functioning git repository that contains the Hello World application as well as a package.json file, which is used by npm (Node’s dependency manager).

Install the package dependencies with npm:

1
$ npm install

Configure the app

Port

The Hello World example application listens on the HTTP port defined by the environment variable PORT or 8080 by default. You can change the port by creating a .env file in your app's root directory and specifying the desired port value, like this:

1
PORT=8080

Token secret

Callbacks triggered by the ONEm platform contain a jwt token in the authorzation header. The jwt token carries the unique identity of the ONEm user so that your app can differentiate requests from different users. In order to verify jwt tokens that are sent by the ONEm platform, the token secret should be configured in two places:

  1. Your local environment
  2. In the developer portal (see "Register the App in the Developer Portal" below).

Configure the secret in the .env file, for example:

1
TOKEN_SECRET=87654321

Run the app

Start the app with:

1
$ npm run start

You should see output similar to the following in the console:

1
Listening on port 8080

Now run ngrok to create a secure tunnel to your local computer so that your app is visible to the ONEm servers.

1
$ ngrok http 8080

ngrok will launch a continuous display to the console. Make a note of the HTTP or HTTPS forwarding address. In the example below the address is http://6e3f3fce.ngrok.io:

1
Forwarding        http://6e3f3fce.ngrok.io -> http://localhost:8080

Navigate to the forwarding link in your browser and you should see a Hello World greeting.

The Hello World example app expects to receive HTTP requests as users perform certain actions. We call these callback notifications. The Hello World example app expects to receive callback notifications on the base path: /api. The ONEm platform will need to be configured with the fully qualified URL of this endpoint, including the base path. In our example above, the callback url would be http://6e3f3fce.ngrok.io/api. We shall configure this callback url in the next step.

Tip

Make a note of your callback url and token secret, you will need them in the next step.

Register the app in the Developer Portal

If you have not already done so, sign-up for a free ONEm developer account.

Register your app on the ONEm Developer Portal by selecting the Create app option. You will need to provide:

  1. A short description of your app
  2. The app category, just select "Business"
  3. The callback url you obtained from the previous step
  4. The value of token secret that you provided in your environment settings

Make sure the details are saved correctly in the portal.

Info

Don't worry about the other app details at this stage, we will use them later in the advanced tutorials.

Test the app

In the ONEm Developer Portal, select the Test Client tab and register your mobile number. Then in the input field, enter # followed by your app's name, for example #HELLO.WORLD if your app is called hello.world.

If you have completed everything correctly, the ONEm system should respond with a menu, similar to the below:

1
2
3
4
5
#<APP_NAME>
A First option
B Second option
C Third option
--Reply A-C

If you see the above, congratulations, you have successfully installed your first app. Give yourself a pat on the back and then head over to the advanced tutorials to get to know ONEm better.

If you don't see the above done worry, go back and check that each step has been followed properly and your program will soon be up and running.