1. Tutorials
  2. Integrate M2X with Appery.io

Integrate M2X with Appery.io

This tutorial will walk through all the steps necessary to request data from M2X for display within an application built using Appery.io. Appery.io is a cloud-based platform with visual development tools for building iOS, Android, Windows Phone & HTML5 applications.


The application we’ll be building will leverage the List Data Streams endpoint of the M2X API in order to list a Device’s Streams along with their last logged value. Let’s get started! :

Creating App and REST Service

The following steps will walk you through creating a new Appery.io application, and setting up the REST Service which will interface with M2X:

  1. Head to Appery.io and select Create New App (Appery.io account required). Under the Template tab select “jQuery Mobile app”, as this tutorial will be leveraging jQuery.


  2. Select Create New > Service


  3. Now we will create a “Settings (REST Settings)” service. This is where settings for the M2X-REST service will be stored. The variable for the dynamic part of the M2X API endpoint URL will be stored here. Since we’ll be making a request to the List Data Streams endpoint, that would be the id parameter, which is the Device ID for the device being targeted.

    • Enter a name for the settings service, such as “ListStreamsSettings”
    • Select “Settings (REST Settings)” as the Service type
    • Select “Create Service”

  4. Add the id parameter:

    • Enter id as the parameter name
    • Leave “value” blank
    • Enter “Device ID” as the Description (optional)

  5. Now let’s create the REST Service which will connect with the List Device Streams endpoint we are targeting. Just as we did before when creating the REST Settings Service, select Create New > Service, enter a name for the service (e.g. “ListStreams”), specify the service type as “REST”, and select “Create Service”.


  6. Configure the REST service Settings:

    • URL: Enter the URL for the List Data Streams endpoint https://api-m2x.att.com/v2/devices/{id}/streams
    • Method: GET
    • Response Data Type: JSON
    • Settings: select the REST Settings file created previously (e.g. “ListStreamsSettings”)

  7. Configure the REST service Request by adding the X-M2X-KEY header, which is required to authenticate the request to M2X:

    • Name: X-M2X-KEY
    • Value: leave this blank as we'll be assigning the value elsewhere

Connecting UI to the REST Service

The next steps will connect the REST Service created in the previous section to the UI for the app:

  1. Expand the Pages section in the left navigation pane, and open startScreen (the default starting Page):


  2. While in the Design section of the Page editor, drag-and-drop a button to the startStreen page. This button will be configured to initiate the HTTP request to M2X.


  3. Select “Events”, located at the bottom of the Page editor screen, to configure the button to trigger a JavaScript event. Configure the button as follows and enter the following code, which will run whenever the button is clicked:

    • Component: the button we just created
    • Event: Click
    • Action: Run JavaScript
    // This injects the Device ID into the REST Service Settings
    // Replace  with the target Device’s ID
    ListStreamsSettings.id = '';
    
    // Executes the get_all_streams event
    get_all_streams.execute({
        data:{
       },
        headers:{
            // This injects the authorized M2X API Key into the `X-M2X-KEY` header of the request
            // Replace  with an M2X API Key authorized to access the target Device
            'X-M2X-KEY': ''
        }
    });

  4. Drag-and-drop a block of HTML below the button. This is where the data returned by M2X will be displayed:


  5. Edit HTML and copy the following into the HTML Source tab

    <!-- "error" section will display any errors returned by the API, for debugging purposes -->
    <div id="error"></div>
    <!-- "header" section will display a header above the list below -->
    <div id="header"></div>
    <!-- "list" will display the list of streams/values returned by M2X -->
    <ul id="list"></ul>

  6. In the Data section of the startScreen Page, add a datasource.

    • In the first drop down, select “Service”
    • In the second drop down, select the “ListStreams” service created earlier
    • Select “Add” to add the datasource

  7. Name the datasource "get_all_streams"


  8. Delete the default “Mapping” actions that are set for “Before send” and “Success”, we won’t need these:


  9. Add the "Run Javascript" action to the "Before send" state:


  10. Enter the following jQuery for the “Before Send” Run Javascript action. This is just some cleanup code to ensure that all fields in the HTML block are cleared before each request. Note: that we’re building a jQuery app within Appery.io, which supports use of jQuery wherever custom JavaScript can be used.

    $( "#error" ).empty();
    $( "#header" ).empty();
    $( "#list" ).empty();

  11. Add the "Run Javascript" action to the Success state, with the following jQuery code:

    // Clear error, if any
    $( "#error" ).empty();
    
    $( "#header" ).append("All streams:");
    
    $.each(data.streams, function(index, stream) {
         $( "#list" ).append( "
  12. " + stream.name + " - " + stream.value + "
  13. " ); });
  14. Add the "Run Javascript action" to the Error state, with the following JS:

    $( "#error" ).replaceWith( "ERROR: " + errorThrown );

The Final Product