@datorama/sdk

    0.70.3 • Public • Published

    SDK

    Usage

    Basic Setup

    The Datorama SDK for JavaScript doesn't have any standalone files that need to be downloaded or installed, instead you simply need to include a short piece of regular JavaScript in your HTML that will asynchronously load the SDK into your pages. The async load means that it does not block loading other elements of your page.

    <script>
        window.datoAsyncInit = function() {
          DA.init();
        };
    
        (function(d, s, id){
            var js, dajs = d.getElementsByTagName(s)[0];
            if (d.getElementById(id)) {return;}
            js = d.createElement(s); js.id = id;
            js.src = "https://cdn.jsdelivr.net/npm/@datorama/sdk";
            dajs.parentNode.insertBefore(js, dajs);
        }(document, 'script', 'datorama-jssdk'));
    </script>

    This code will load and initialize the SDK.

    The method DA.init() is used to initialize and setup the SDK.

    All other SDK methods must be called after this one, because they won't exist until you do.

    Consuming the SDK

    There are two options to consumes the SDK:

    • By injecting the following JS snippet into the body:
    <script>
        (function(d, s, id){
            var js, dajs = d.getElementsByTagName(s)[0];
            if (d.getElementById(id)) {return;}
            js = d.createElement(s); js.id = id;
            js.src = "https://cdn.jsdelivr.net/npm/@datorama/sdk";
            dajs.parentNode.insertBefore(js, dajs);
        }(document, 'script', 'datorama-jssdk'));
    </script>

    The src attribute is point to the latest version of the SDK, stored in a CDN. It's recommended to consume a specific version of the SDK, to avoid from breaking changes in future release. Just add an @ sign followed by the version number. For example: https://cdn.jsdelivr.net/npm/@datorama/sdk@0.1.7-beta

    • You can consume the SDK as a module, using ES6 imports, requireJS or any other module system.

    Installing with NPM:

    $ npm install @datorama/sdk --save

    Installing with Yarn:

    $ yarn add @datorama/sdk
    init Options
    Function Default Value Description
    token undefined An optional API token (TBD)
    logger undefined A custom logger implementation. Use this to print debug logs.
    promiseBased false Whether you'd like to work with promises, rather than callbacks
    Debugging

    Pass a custom logger implementation to the init function. In the following example, we're using console.log to print debug messages:

      DA.init({
        logger: {
          log: console.log
        }
      });

    Events

    You can subscribe to different events from the SDK, such as the APP events.

    All events are asynchronous. When subscribing to an event, pass a callback function as the last parameter. This function will be invoked once the event has emitted.

    The callback functions should be in the style of node callback (AKA "nodeback"):

    function myCallback(error, data): void {
    
    }

    APP API

    Function Description
    onLoad Subscribe to the loaded event.
    install Finish installation
    onLoad event

    Use the onLoad event to notify when the application has loaded.

    DA.init();
    
    DA.app.onLoad(function (error, data) {
        console.log(`Run mode: ${data.mode}`); // print INSTALL / RUN
        console.log(`App configuration: ${data.config}`); // print the app stored configuration
        console.log(`App: ${data.metadata}`); // print the app instance properties
        console.log(`Params: ${data.params}`); // print context parameters (accountId, workspaceId, userId)
    })
    send install event

    Use the install function to finish the installation of your application. The function received an optional configuration object for this application instance. You can use the same config later, in the RUN mode.

    const myCustomConfig = {
      installDate: new Date()
    };
    
    // save a custom configuration in the app instance,
    // and complete the installation.
    DA.app.install({
      config: myCustomConfig
    })

    You can retrieve the same configuration later, by subscribing to the onLoad event (Run mode only):

    DA.app.loaded(function (error, data) {
        console.log('The app installed at: ' + data.config.installDate);
    });

    REST API

    In order to fetch data from Datorama, use the api service.

    Example:

    // GET request
    DA.api.get("/v1/resource", function(error, response) {
      if (error) {
        console.log("Error: " + error);
      }
      else {
        console.log(response.data);
      }
    });
    
    
    // POST request
    DA.api.post("/v1/resource", "POST", {name: 'your_name'}, function(error, response){
    
    });
    
    // PUT request
    DA.api.put("/v1/resource", "PUT", {name: 'your_name'}, function(error, response){
    
    });

    The above methods are just a shorthand for the request method`:

    // as arguments
    DA.api.request(path: string, method: "GET" | "POST" | "PATCH", params: {}, callback);
    
    
    // or as a single object
    DA.api.request({
      path: string,
      method: "GET" | "POST" | "PATCH",
      params: {}
    }, callback);

    Promise Based API

    By default, subscription to different asynchronous APIs can be done by passing a callback function, as mentioned earlier. However, working with Promises can be slightly easier when chaining multiple APIs calls, into one.

    In order to activate this feature, just set promiseBased = true in the init function. From now on, you can avoid passing a callback function, and use the Promise API.

    In the following example, we instantiate the SDK with the promiseBased flag set to true, and subscribing to the onLoad event, as we seen earlier, but with a Promise:

    DA.init({
        promiseBased: true
    });
    
    DA.app.onLoad().then(function(data){
        // app loaded successfully!
    }, function(error){
        // something went wrong :(
    });

    The real strange of promise shine when chaining multiple asynchronous calls:

    const requests = [DA.api.get('first_request'), DA.api.get('second_request')];
    
    Promise.all(requests).then(function(response){
        console.log(response[0]); // print the response of the first_request
        console.log(response[1]); // print the response of the second_request
    }).catch(function(error){
        // something went wrong :(
    });

    Mix callbacks and Promises:

    When you choose to work with promises, you can still working with callbacks as well, as long as you pass the callback function. Consider the following example:

    DA.init({
        promiseBased: true
    });
    
    // using promise
    DA.api.get('v1/get/1').then(function(response){
        console.log('hello from the promise!');
    });
    
    // using callback
    DA.api.get('v1/get/2', function(error, response){
        console.log('hello from the callback!');
    });

    Cross Browser Compatability

    Promises are a great option when working with many asynchronous calls. Under the hood, the SDK is using the native browser implementation for Promises, which supports only evergreen browsers. If you wish to support legacy browsers (IE11), just add a Promise polyfill: https://github.com/paulmillr/es6-shim

    More on Promises and browser compatabillity: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise


    Working with Mock Data

    It's possible to work with mock data, when the SDK running inside Datorama, and even when it's standalone. Any options you set in the mock, will override the default parameters.

    The mock should be used only when:

    1. You want to test your code before the deployment to datorama. Make sure this is only activated in your DEV environment.
    2. You want to provide mock for the requests you already have in your app - for the demo mode.

    Mock Interface:

    The SDK init function expose a mock parameter which provides the following interface:

    Field Description
    appLoad Override the onLoad response.
    requests Provides a mock data for API requests.

    Mocking appLoad

    Use the appLoad when you want to override the received app configuration you get via DA.app.onLoad.

    DA.init({
        mock: {
            appLoad: {
                mode: 'RUN' | 'INSTALL' | 'DEMO', // the the app mode to install
                config: {}, // override the saved configuration
                params: {}, // override the app's params (workspaceId, accountId, userId)
                metadata: {} // override the app instance
            }
        }
    });

    Example

    DA.init({
        mock: {
            appLoad: {
                mode: 'INSTALL',
                config: {
                    firstName: 'Amit'
                }
            }
        }
    });
    
    DA.app.onLoad(function(err, data){
        console.log(data.mode); // print to the console: 'INSTALL'
        console.log(data.config); // print to the console: {firstName: 'Amit'}
    })

    Mocking HTTP Requests

    Mocking HTTP requests can be done via the requests field, in the mock configuration object. This is useful for simulate HTTP calls - it means you don't have to change your code in order to test your application, or the best option - you can use the mock to provide a demo to your users, without changing your code!

    Let's see it in action:

    DA.init({
        mock: {
            requests: {
                'v1/get/my/data': {
                    success: {
                        status: 200,
                        data: 'here is your data'
                    }
                }
            }
        }
    });
    
    DA.api.get('v1/get/my/data', function(err, data){
       console.log(data); // print to the console: here is your data
    });

    Set mock for different HTTP methods (such as POST and PUT), can be done in the same way:

    DA.init({
        mock: {
            requests: {
                'v1/post/my/data POST {id: 1}': {
                    success: {
                        status: 200,
                        data: 'success'
                    }
                },
                'v1/put/my/data PUT {id: 1, field: 'new_value'}': {
                    success: {
                        status: 200,
                        data: 'success'
                    }
                }
            }
        }
    });

    This is all you need in order to set a mock.

    More Advnaced Examples

    Sometimes you want to mock complex request body, and use them in your POST/PUT methods. Using the string convention (as mentioned above) is not always comfterble. It's possible to use a complex object as the request key, rather then a string. Let's see it in action:

    DA.init({
    
        // we store the requests in JS map, so we'll be able to use a key object
        var requestsMock = new Map();
        // define our mocks
        requestsMock.set({
            path: 'v1/post/my/data',
            method: 'POST',
            params: {
                id: 1,
                firstName: 'Amit',
                lastName: 'Bh',
                location: {
                    city: 'Shoham',
                    zipCode: 123456
                }
            }
        }, {
            success: {
                status: 200,
                data: 'success'
            }
        });
    
        mock: {
            requests: requestsMock
        }
    });

    Fail Response

    Sometimes, you want to simulate failed API requests. In order to achive this behaviour, you can use the error field:

    DA.init({
        mock: {
            requests: {
                'v1/post/my/data POST {id: 1}': {
                    error: {
                        status: 500,
                        data: 'Something went wrong :('
                    }
                }
            }
        }
    });

    This will make your request to fail, with the status code of 500, and the following body: Something went wrong :(


    Development

    Install

    $ npm install

    Build Dev

    $ npm start

    Build Production

    $ npm run build

    To update the version see instructions here: https://datorama.atlassian.net/wiki/spaces/APPS/pages/811106334/Publishing+a+New+APP+SDK+Version

    Keywords

    none

    Install

    npm i @datorama/sdk

    DownloadsWeekly Downloads

    235

    Version

    0.70.3

    License

    Apache-2.0

    Unpacked Size

    2.46 MB

    Total Files

    6

    Last publish

    Collaborators

    • jmeguira
    • yonatanlevy
    • abh86
    • keinans
    • gurdotan
    • org86
    • epessach
    • iglikman
    • ashakked
    • lron
    • samerkinaan
    • amitb
    • nhaimov
    • eliran.aharoni
    • tidhar.peer
    • ritox
    • ofirb25
    • yousef.baba
    • netbasal
    • nina.mordakhay
    • kaufguy
    • idafna
    • roi.orlan