.. |br| raw:: html

   <br />

Rumba Javascript SDK
====================

The Socket Mobile Rumba Javascript SDK is a non-intrusive Javascript SDK that interfaces directly with the Rumba iOS application to provide
a way to modify the user-experience of each web application.




Initializing a Rumba JS instance
--------------------------------

The Rumba instance initialization has 2 arguments:
  * the domain name of the web site or the web app ("www.socketmobile.com" is sufficient. A URL such as "www.socketmobile.com/products/devices" is not needed)
  * the configuration change ID

.. code-block:: Javascript

  import Rumba from './dist/rumba.js'

  rumba = new Rumba('example.com', '5ff172b0-14a7-45a5-80d3-8743782554a2')
  rumba.addListener('onError', (message) => {
    displayAlert(message);
  });
  rumba.addListener('onSettingsChange', (settings) => {
    console.log('the settings have changed: ', settings);
    // Update the UI with the new settings
    // Decide whether to save the new settings inside the Rumba instance
    updateUI(settings);
    rumba.applySettings(settings);
  });


Specifying a web application domain name
----------------------------------------

This allows the Rumba iOS application to have a `DomainConfiguration` for each web application.

In the example above, we use :title:`example.com` as the domain name

The purpose of specifying a domain name is to prevent conflicts with configurations from other web applications using Rumba.
By providing a domain name ("www.socketmobile.com"), web applications have the ability to set up configurations that are specific to itself, thus allowing per-domain configurations.

Configurations for each web application can be completely different from one another.

Most importantly, specifying a domain name prevents web applications from modifying configurations for other web applications.



Configuration change ID
-----------------------
The concept of change ID is used to identify a configuration with a unique identifier.
Since this parameter must be string, the web developer has no restriction on what this string can be.
For example, it may be something of importance to the web application.

In the example above, we use :title:`5ff172b0-14a7-45a5-80d3-8743782554a2` for the change ID

The purpose of the change ID is for the Rumba JS API to be notified when changes have been made to the configuration that was created during initialization.
Consider the scenario:
  * A Rumba JS API instance was initialized change ID was "1234".
  * At some point in the life cycle of the web application, changes were made to this instance.
  * This will result in the change ID being updated to "6789".
  * The Rumba JS API will determine that changes have been made due to the difference of the change ID.

If the Rumba iOS application modifies the configuration for a web application, the web application using
the Rumba JS API will be notified that changes have been made and verify if these changes are authorized.

This prevents end-users that are interacting with the web application on iOS device from making undesired changes
to the configuration.

Consider the scenario:
  * An end-user is interacting with the Rumba iOS app on an iPad / kiosk in a public storefront.
  * The end-user modifies the configuration for the web application that the storefront has on the iPad.
  * The changes make it difficult for the next user to use the iPad as intended.
To prevent such a scenario, Rumba JS API will be notified that the change ID is different. (which indicates that the configuration has been modified)
Then, Rumba JS API will verify that the changes made to the configuration are authorized.




Handing over from a web application to Rumba
---------------------------------------------------------

If you are viewing a web page in Safari, and would like to automatically open this page in Rumba,
this can be done by adding a few lines to your <script> tags (or equivalent starting point):

.. code-block:: Javascript

  function handoverURLToRumba() {

    // Get the URL of the current web page.
    var finalUrl = document.URL;

    // If the web page is already being displayed in Rumba, do no further action.
    if (/(Rumba)/.test(navigator.userAgent) == false) {

      // If the web page is being loaded from an Apple device,
      // (Rumba can only be installed on iOS devices as of now)
      if (/(iPhone|iPad|iPod)/.test(navigator.userAgent)) {

        // Finally, display a prompt that asks the user if they would like
        // to hand over this web page to the Rumba application
        window.location = "Rumba://" + finalUrl;
      }
    }
  }




.. toctree::
  :maxdepth: 2

  rumbaJsDomainConfiguration
  rumbaJsCommunicationPattern
  rumbaJsApiListener
  rumbaJsApiApplyConfig