Part 1 - Setting up
In this article, I’ll show you how to build an example micro-app from scratch using our simple Node.js SDK. The tutorial assumes a basic knowledge of Node.js.
We’ll retrieve the movie details courtesy of the free api provided by http://themoviedb.org (please make sure to abide by their terms)
The ONEm platform lets you host your micro-app anywhere on the Internet. For local testing, We’ll use ngrok to provide a publicly accessible URL so that we have a bridge between our app running on localhost and the ONEm Framework.
- Sign up for a free themoveidb api key here
- Sign up for a free ONEm developer account here
- Install ngrok from here
When a user makes a request from a web-widget or via SMS, the ONEm Framework will invoke an HTTP callback to the micro-app’s web server. The micro-app should respond with HTTP status code 200 and include, in the response body, some JSON which tells the ONEm Framework how to render the response to the user.
Our Node.js SDK provides an abstraction of the JSON format so you don’t have to worry about the details. You have two options, you can use the SDK to produce JSON by passing parameters to the functions provided, or alternatively you can use a templating library and write your micro-app’s views in HTML :) In this tutorial, we’ll be using the second option and specifically pug as the templating language, you can use ejs instead if you prefer.
Ok, enough chat, let’s get coding!
Project Structure and Code¶
The code used in this tutorial can be accessed via the git repository here.
Our project structure will look like this:
1 2 3 4 5 6 7 8 9 10 11 12
Install Express and the project’s base dependencies:
We’ll also use the ONEm Framework’s Node.js SDK:
index.js in the project root with the following content:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
When users make requests from our micro-app, such as selecting a menu option or submitting a form, the ONEm Framework will issue a HTTP request to the micro-app’s callback path. In the index.js we set /api as the ‘basepath’ for all requests coming from the ONEm Framework.
When the micro-app is launched for the first time by a user, the ONEm Framework will display the micro-app’s “landing page”. This is a bit like the index.html of a typical web application. The landing page is invoked by the ONEm Framework issuing a request to the micro-app’s API base path, in our case /api.
So we’ll want our app to handle a basic call to
GET /api and respond with some initial content that the user will see.
For our example, we’ll create a static menu, so that our users can view three different movies:
When the user clicks on a movie title, we’ll show the movie’s image and description.
First off, let’s create the landing menu options by creating a
landing.pug in the /views folder:
1 2 3 4 5 6 7 8 9
And let’s connect the base route in Express in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
/routes/index.js contains a route for the movie view page, when the user clicks on a movie title, the ONEm Framework will issue an
HTTP GET callback to the href associated with that option, eg in landing.pug we have the following line:
Later in this tutorial, we will tell the ONEm Framework to use the base path of
/api, which will eventually translate into
HTTP GET /api/movie/76341 when the user selects to view Mad Max.
Ok, so a quick recap. We have created two views using pug. Our web server is ready to accept callbacks from
So what’s remaining now is to complete the setup of our micro-app.
- Create a
.envfile in the project root path:
- We’ll use ngrok to give us a publicly accessible url to our micro-app at localhost:3000.
Copy the link provided by ngrok, it will be something like
In the ONEm Developer Portal, select Create App and set the callback path to your micro-app appending
/apito the base path, eg:
/public/index.htmlof your Micro-app:
1 2 3 4 5 6 7 8
This code snippet can be included in any website, if you have access to another website’s
index.html, then go ahead and try it.
Fire up your micro-app:
In your browser, visit localhost:3000 (or where ever your app is configured to listen)
The ONEm micro-app should be visible in bottom right-hand corner. Click the icon to open.
You can also view the SMS client from the ONEm Developer Portal test client. After registering your mobile number, you can test out the SMS interface by entering # followed by your micro-app name in the input box.
Now head over to part 2 where things get a bit more interesting...