Admobilize Node SDK

Overview

**AdMobilize Node SDK **, is a node module to connect in an easy way to the **AdMobilize API **

####With this module you can

• Register an application
• Create AdMobilize users
• Authenticate AdMobilize users

Try this module

Follow this steps

Install node

• Go to http://nodejs.com/downloads.
• Download the installer for you OS and follow the wizard steps

###Clone the repo

git clone https://bitbucket.org/admobilize/admobilize-node-sdk.git

Install depedencies

cd admobilize-node-sdk
npm install 

1) A simple example to authenticate a client

   // You need to incluide the Admobilize SDK module

   var admobilize = require('path_to_sdk_module/admobilize.js');
   var admobilizeSDK = new admobilize(); 

   //create a new client instance
   var myClient = new admobilizeSDK.client('your_cliend_id','your_client_secret');

   //create a new authenticator instance
   var myAuthenticator = new admobilizeSDK.authenticator();


   /**
   *To authenticate a client calling the authenticateClient method 
   *from the Authenticator module passing the client instance and a callback function
   */

    myAuthenticator.authenticateClient(myClient,function(error, responseJSON) {
     //Do something with my authenticated client

  });

2) How to register a new user

You need to do the steps in the last example and do somethig like this:

  // Incluide the AdMobilize
  var admobilize = require('path_to_sdk_module/admobilize.js');
  var admobilizeSDK = new admobilize(); 

  //create a new user instance 
  //set username , password and a client object
  var newUser =  new admobilizeSDK.user('a_username','a_secure_password', myClient);
  
  //create a new register instance
  var myRegister = new admobilizeSDK.register();

  /**
   * call the registerUser method 
   *from the Register module passing the client instance , user instance and a callback function
   */
   myRegister.registerUser(client,newUser,function (error, responseJSON) {


     //Do something with my new registered user

     //if an error occurs the error variable will be an Error instance  and responseJSON will be an object with the response from the server that describes the error, if none error occurs  the error variable and responseJSON  will be undefined
     //
  });

3) Authenticate a registered user

You need to do authenticate a client (first example) and then authenticate the user.

   // Incluide the AdMobilize
  var admobilize = require('path_to_sdk_module/admobilize.js');
  var admobilizeSDK = new admobilize();

  //create a new client instance
  var myClient = new admobilizeSDK.client('your_cliend_id','your_client_secret');
   

  //.... do the same as the first example to authenticate our client

  /*
  * create a new user instance , if the user is already registered you just need set the username ,password, and a client object
  * if is not registered yet you need to do the steps in the second example
  */

  var myUser =  new admobilizeSDK.user('a_username','a_secure_password', myClient);

   //create a new authenticator instance
   var myAuthenticator = new admobilizeSDK.authenticator();


  
   /**
   *To authenticate an user calling the authenticateUser method 
   *from the Authenticator module passing the user instance, user instance and a callback function
   */

    myAuthenticator.authenticateUser(myUser,function(error,responseJSON) {
     //Do something with my authenticated user
     
     

  });

4) Register a device

You need to do authenticate a client (first example) , authenticate the user and then register a device.

  // Incluide the AdMobilize
  var admobilize = require('path_to_sdk_module/admobilize.js');
  var admobilizeSDK = new admobilize();

  //create a new device instance
  //set device name and description  and an user object
   var myDevice  = new  admobilizeSDK.device('name','description', myUser);

   var  myRegister = new  admobilizeSDK.register();
    myRegister.registerDevice(registeredUser, myDevice , function(error, responseJSON) {

       //do something with the registered device
    });
     

  });

Note: When the device is successfully registered the device gets a device token that you can access with the method getDeviceToken from the Device mudule

6) Heartbeat

Register a device start automatically a proccess named "Hearbeat" that verify the connection to the admobilize API server, you can verfy the status of the connection with the isAlive method from the Device module

   var status = myDevice.isAlive();// resturns a boolean value , is true if the server connection is OK.

The Heartbeat proccess use the user access token to do the request and verfy the connection with the server , if the user token expires the proccess stop and do a resfresh token request automatically to get a new token , then the proccess restart.

By default the proccess runs every 30 seconds (30000 miliseconds) , you can change this value in the config.js file (admobilize-node-sdk/config/config.js) changing the HEARTBEAT_INTERVAL variable.

6) Submit data point

To submit point information you need a registered device (like the last example), you can send geolocalitation info and files

  // Incluide the Device module
    // Incluide the AdMobilize
  var admobilize = require('path_to_sdk_module/admobilize.js');
  var admobilizeSDK = new admobilize();

  //my registered device
   var myRegisterDevice  = new admobilizeSDK.device('device_id');

    myRegisterDevice.submitDataPoint(
         'access_token' ,  //access token from a authenticated user
         'a json encoded', //he data point JSON encoded. e.g. {"ty":"mc","cl":{"loc_type":0,"si":9,"aps":false},"sr":[]}
         'file data',  // data from a file , like a .png, .jpg 
         function(error, responseJSON) { //  a callback function
           
         }
      );

     

  });

Note: You can get the "file data" from any file with the "fs" module from Node.js, like this

  
  var fileSystem = require('fs');
  var fileData = fileSystem.createReadStream('path_to_my_file' , 'encode_type' );  // set the path to the file and an encode type (ex: 'utf8')

7) Get devices associated to an user

You can get a list of devices associated to an user.

   // getDevices method recives a callback function and a options json , these options are optional ,
   //some options are  pagination_page,pagination_limit and pagination_sort
   myUser.getDevices(callback, options); 

Get a specific device

   // getDeviceById method recives a  deviceId, a callback function and a options json , these options are 
   // optional.
   myUser.getDeviceById("deviceId",callback, options); 

8) Get data from devices associated to an user

Get a json with the data from devices associated to an user

   // getDevicesData method recives a callback function and a options json 
   myUser.getDevicesData(callback, options); 

###Run the examples The examples folder has a few examples that you can run:

####Authenticate a client AuthenticateClient.js creates a new client instance and authenticate it using the AdMobilize API,if your want to try it follow the next steps.

 cd examples
 node AuthenticateClient.js 

####Register an user

RegisterUser.js creates a new client instance and authenticate it ,creates an user and register it using the AdMobilize API , if your want to try it follow the next steps.

 cd examples
 node RegisterUser.js

####Note If you have an "User Already exists" error you need to change the username to create a new user or if you have permissions clean your user's collection.

####Authenticate a registered user

AuthenticateUser.js creates a new client instance and authenticate it ,authenticate the user from RegisterUser.js to the AdMobilize API.

 cd examples
 node AuthenticateUser.js

####Submit data point

SubmitDataPointTest.js have all the steps , autheticate a client, register a new user, authenticate an user , register a device and sends data from a registered device (geolocalication info and a png file)

 cd examples
 node SubmitDataPointTest.js

####Get devices

GetDevicesTest.js get all devices from an user, get a specific device by id and retrieve data from that device

 cd examples
 node GetDevicesTest.js

###Final notes

• You can view the documentation from the Admobilze node SDK in the index.html file in admobilize-node-sdk/out/index.html

• If you want to change the host url or the paths you can do it in the config.js file in admobilize-node-sdk/config/config.js