Intent

Enterprise Browser 3.7

Overview

The Intent API provides an inter-application broadcast message-passing framework.

Enabling the API

There are two methods of enabling the Intent API:

  • Include all 'ebapi' modules
  • Include only the required API modules

Both methods are explained below.

Either way, the included files will be found in: /Enterprise Browser/JavaScript Files/Enterprise Browser, a directory on the computer that contains the Enterprise Browser installation.

Include all JS API modules

To include all JavaScript APIs, copy the ebapi-modules.js file to a location accessible by your app's files and include the JavaScript modules file in your app. For instance, to include the modules file in your index.html, copy the file to the same directory as your index.html and add the following line to the HEAD section of your index.html file:


<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

This will define the EB class within the page. Note that the path for this file is relative to the current page (index.html). Any page on which the modules are required will need to have the required .js file(s) included in this fashion.

Include only the required modules

To include individual APIs, you must first include the ebapi.js in your HTML, and then the additional required API file(s). For instance, to use the Intent API, add the following code to the HTML file(s). Again, this assumes that relevant API files have been copied to the same directory as the HTML.


<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.intent.js"></script>

In the code lines above, notice that ebapi.js is included first, followed by eb.intent.js, which is the Intent API for Enterprise Browser. This coding is required on each HTML page whenever an individual API will be called from that page.


Methods

send(HASH params)

Sends an intent. The receiver of the intent can be another application that is listening for this Intent characteristic or, on Android, the receiver can be a native Android application set up with an Intent-Filter that will trigger based on the parameters of this method.

Android Note: On Android, the callback should be used only when the intentType is set to START_ACTIVITY. The only valid way for an Android app to pass a private file from a package directly to another application is to set the 'uri' parameter with content URI.

Parameters

  • params : HASH

    A hash-map with intent parameters.

    • intentType : STRING

      Type of Intent to send.

      Possible Values :

      Constant: Intent.BROADCAST
      String:broadcast
      Use the intent as broadcast intent.
      Constant: Intent.START_ACTIVITY
      String:startActivity
      Use the intent to start a UI activity. Platforms: Android
      Constant: Intent.START_SERVICE
      String:startService
      Use the intent to start a background service. Platforms: Android
    • permission : STRING

      Permission used to send a broadcast intent. Platforms: Android

    • action : STRING

      Intent action. See Android docs for possible values. Use the Constant Value instead of the actual Constant Name. For example, for the Constant ACTION_PICK use 'android.intent.action.PICK' instead. Platforms: Android

    • categories : ARRAY

      List of intent categories. See Android docs for possible values. Use the Constant Value instead of the actual Constant Name. For example, for the Constant CATEGORY_HOME use 'android.intent.category.HOME' instead. Platforms: Android

      • Object : STRING

    • appName : STRING

      Explicit name of the application to run on the device. The platform will determine the value to use. On Android, use the application package name. On Windows use the application/executable name. For shared runtime applications, the application name is taken from the 'Name' attribute in the Config.xml file.

    • targetClass: STRING

      Explicit name of the class in the application that will receive the intent. Must be specified if and only if 'appName' is defined. Platforms: Android

    • uri: STRING

      Open the application associated with the URI. Behavior may be different on different platforms and on software installed. For example, open URL with 'http://' prefix usually executes the Web Browser installed on system and opens the URL in that browser. On Android, this is similar to Intent.setData(). For example, if sending a Map Intent, you might set this value to something like geo:47.6,-122.3.

    • mimeType : STRING

      MIME type of data defined in the intent. For example, for Plain Text one would use 'text/plain.' On Android, this is similar to Intent.setType.

    • data : HASH

      Data to be sent within the intent. On Android, this is similar to Intent.putExtra, and 'data' should contain a HASH of Extra-String/Value pairs. The 'Value' type of the 'Extra' can be a String, Integer, Boolean, Double, Nested Bundle, Bundle Array, or Parcelable Array List. Other object types are not supported at this time. For sample code, please refer to examples section below. Use the full constant string 'android.intent.extra.TEXT' in place of Intent.EXTRA_TEXT.

    • pendingIntent: HASH

      An optional attribute; hash map with pending intent-related parameters.

      • name: STRING

        Name of pending intent to be sent.

      • requestCode: INETEGER

        Private request code for the sender that will be associated with the result data when it is returned. The sender cannot modify this value, allowing the user to identify incoming results. The requestCode should be greater than 1000 for PendingIntent.

      • flag: INTEGER

        An optional attribute; hash map with pending intent-related parameters.

      • Possible Values:

      • Constant: Intent.FLAG_UPDATE_CURRENT

      • int:134217728

        Flag indicating that if the described PendingIntent already exists, then keep it but replace its extra data with what is in the new intent.

      • Constant: Intent.FLAG_ONE_SHOT

        int:1073741824

        Flag indicating that this PendingIntent can be used only once.

      • Constant: Intent.FLAG_NO_CREATE

        int:536870912

        Flag indicating that if the described PendingIntent does not already exist, then simply return null instead of creating it.

      • Constant: Intent.FLAG_IMMUTABLE

        int:67108864

        Flag indicating that the created PendingIntent should be immutable. This means that the additional intent argument passed to the send methods to fill in unpopulated properties of this intent will be ignored.

      • Constant: Intent.FLAG_CANCEL_CURRENT

        int:268435456

        Flag indicating that if the described PendingIntent already exists, the current one should be canceled before generating a new one.

      • callback : CallBackHandler

    Callback

    Async Callback Returning Parameters: HASH

      • responseCode : INTEGER

        Response code passed to Android Activity.setResult() method. RESULT_OK = -1. Check Android Docs for more information. Other attributes, such as 'uri' may be returned depending on the Intent that was triggered. Possible parameters include the same params that are used in this 'send(params)' method. Platforms: Android

    Returns

    Synchronous Return:

    • Void

    Platforms

    • Android
    • Windows Mobile

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • EB.Intent.send(HASH params)

    startListening()

    Start listening for custom intents.

    Parameters

    • callback : CallBackHandler

    Callback

    Async Callback Returning Parameters: HASH

      Returns

      Synchronous Return:

      • Void

      Platforms

      • Android
      • Windows Mobile

      Method Access:

      • Class Method: This method can only be accessed via the API class object.
        • EB.Intent.startListening()

      stopListening()

      Stop listening for custom intents.

      Parameters

      • callback : CallBackHandler

      Returns

      Synchronous Return:

      • Void

      Platforms

      • Android
      • Windows Mobile

      Method Access:

      • Class Method: This method can only be accessed via the API class object.
        • EB.Intent.stopListening()

      ENABLE

      Used to enable or disable the Enterprise Keyboard.

      Parameter values:

      • TRUE: EKB enabled and shown whenever device user taps on an input field.
      • FALSE: EKB disabled and DOES NOT show even after using SHOW API or tapping on an input area.

      Examples

      Enable EKB:
          var bool = new Boolean(true);
          var data= {'ENABLE' : bool};
          var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_UPDATE", "", "", "", "", "", data);
          EB.Intent.send(params, intentReceived);
      
      Disable EKB:
          bool = new Boolean(false);
          var data= {'ENABLE' : bool};
          var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_UPDATE", "", "", "", "", "", data);
          EB.Intent.send(params, intentReceived);
      

      GET (available layouts)

      Returns a list of custom key layouts currently available in the device.

      Example

      Get available key layouts:
      var propertiesToRetrieve = ["AVAILABLE_LAYOUTS"];
      var data= {'PROPERTIES_TO_GET' : propertiesToRetrieve};
      var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_GET", "", "", "", "", "", data);
      document.getElementById('availablelayouts').style.visibility = 'visible';
      EB.Intent.send(params, availablelayouts);
      

      GET (current layout)

      Returns the current key layout group and the current key layout name. If Enterprise Keyboard is the current keyboard, returns the currently selected EKB layout.

      Example

      Get current key layout group and layout name:
      var propertiesToRetrieve = ["CURRENT_LAYOUT_GROUP","CURRENT_LAYOUT_NAME"];
      var data= {'PROPERTIES_TO_GET' : propertiesToRetrieve};
      var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_GET", "", "", "", "", "", data);
      EB.Intent.send(params, currentlayout);
      

      SET (key layout)

      Sets the custom layout in Enterprise Keyboard. While sending the intent to set the key layout, developer must add CURRENT_LAYOUT_GROUP and CURRENT_LAYOUT_NAME parameters as extras. Once key layout is set in Enterprise Keyboard, requested application receives a response intent containing RESULT_CODE and RESULT_MESSAGE extras.

      Example

      Set a custom layout for use by the app:
      var layoutGroupName = document.getElementById('selectlayoutgroup').value;
      var layout = document.getElementById('selectlayoutname').value ;
      var bool = new Boolean(false);
      var data= {'CURRENT_LAYOUT_GROUP' : layoutGroupName, 'CURRENT_LAYOUT_NAME': layout};
      var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_UPDATE", "", "", "", "", "", data);
      EB.Intent.send(params, intentReceived);
      

      SHOW

      Used to show or hide the specified key layout.

      IMPORTANT: An app CANNOT hide the keyboard using the SHOW API if the app contains logic to show the keyboard automatically when an activity comes to the foreground

      Parameter values:

      • TRUE: Keyboard is shown when activity is launched, even if the activity does not require input.
      • FALSE: Keyboard is not shown when activity is launched; shown only when the device user taps on an input field.

      Examples

      Show the specified key layout:
          var bool = new Boolean(true);
          var data= {'SHOW' : bool};
          var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_UPDATE", "", "", "", "", "", data);
          EB.Intent.send(params, intentReceived);
      
      Hide the specified key layout:
          var bool = new Boolean(false);
          var data= {'SHOW' : bool};
          var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_UPDATE", "", "", "", "", "", data);
          EB.Intent.send(params, intentReceived);
      

      RESET

      Resets and enables the specified Enterprise Keyboard fixed or custom layout based on current key layout selection.

      Parameter values:

      • TRUE: Keyboard is reset
      • FALSE: Keyboard is not reset

      Notes

      • If a custom layout is selected as the default, the custom layout is reset and displayed when an input field gains focus.
      • If a custom key layout is NOT selected as the default, the Enterprise Keyboard fixed layout is reset and enabled (if previously disabled). EKB is displayed when an input field gains focus.

      Example

      Reset and enable a custom key layout:
          var bool = new Boolean(true);
          var data= {'RESET_LAYOUT' : bool};
          var params = new parameters(EB.Intent.BROADCAST, "", "com.symbol.ekb.api.ACTION_DO", "", "", "", "", "", data);
          EB.Intent.send(params, intentReceived);
      

      Remarks

      Registering Intent Receiver

      For an Android app to receive intent data, the Intent receiver must be registered in the app's Config.xml file. Please refer to the Intent section of the EB Config Reference for more information.


      Examples

      Sending Data Within an Intent

      On Android, sending data within an intent is similar to Intent.putExtra. Data should contain a HASH of Extra-String/Value pairs. The 'Value' type of the 'Extra' can be a String, Integer, Boolean or Double. Notice the use of the full constant string android.intent.extra.TEXT in place of Intent.EXTRA_TEXT.

      
          Android (Java)
      
              intent.putExtra("intent.extra.string", 'Here is the text I am passing to the Intent');
              intent.putExtra("intent.extra.integer", 12);
              intent.putExtra("intent.extra.boolean", true);
              intent.putExtra("intent.extra.double", 14.28);
      
          JavaScript
      
              var data: { 'intent.extra.string' : "Here is the text I am passing to the Intent" ,
                          'intent.extra.integer' : 12 ,
                          'intent.extra.boolean' : true ,
                          'intent.extra.double' : parseFloat("10.55")}
                        };
      
      

      Sending Data Withing a PendingIntent

      
      function sendPendingIntent()
      {
          var pendingintent= { "name": 'pendingIntent',  "requestCode":1000,  "flag":EB.Intent.FLAG_UPDATE_CURRENT};
          var data= {'TOKEN' :token,'APPLICATION_PACKAGE':'com.zebra.mdna.enterprisebrowser'};
          var params = new parameters(EB.Intent.BROADCAST, "", "com.example.myapp.my_intent_action", "", "com.example.myapp", "", "", "", data, pendingintent);
          EB.Intent.send(params, pendingIntentCallback);
      }
      function pendingIntentCallback(param)     
      {  
         console.log('data',param);    
         alert(param.bundle_params.USER_ID);  
         console.log('actionName',param.actionName);        
         var displayStr = "Pending Intent callback received: actiionName" + param['actionName']+"
      name: "+param['name']+"
      reportImage: "+param['reportImage']+"
      bundle_extra: "+param.bundle_params['USER_ID']+"
      nested_bundle_extra: "+param.bundle_params.extra_bundle['Name']; }

      Passing Extras as Nested Bundles

      In some scenarios it might be preferable to pass intent extras as nested bundles or parcelable array objects or lists. Enterprise Browser supports nested bundles as a value type, and they can be created using Java or JavaScript. Examples of all are below.

      Learn more about the Android parcelable class.

      Nested bundle with Java:

      
          Bundle intentConfig = new Bundle();
          intentConfig.putString("PLUGIN_NAME", "INTENT");
          intentConfig.putString("RESET_CONFIG", "true");
          Bundle intentProps = new Bundle();
          intentProps.putString("intent_output_enabled", "true");
          intentProps.putString("intent_action", "com.zebra.datacapture1.ACTION");
          intentProps.putString("intent_delivery", "2");
          intentConfig.putBundle("PARAM_LIST", intentProps);
      

      Nested bundle with JavaScript:

      
          Java Script code:-
          {"intent_output_enabled" : "true","RESET_CONFIG": "true" , "PARAM_LIST":{"intent_output_enabled": "true","intent_action": "com.zebra.datacapture1.ACTION", "intent_delivery": "2" }
          }
      

      Parcelable array object with Java:

      
          Bundle profileConfig = new Bundle();
          profileConfig.putString("PROFILE_NAME", EXTRA_PROFILENAME);
          profileConfig.putString("PROFILE_ENABLED", "true");
          profileConfig.putString("CONFIG_MODE", "CREATE_IF_NOT_EXIST");
          Bundle appConfig = new Bundle();
          appConfig.putString("PACKAGE_NAME", getPackageName());
          appConfig.putStringArray("ACTIVITY_LIST", new String[]{"*"});
          profileConfig.putParcelableArray("APP_LIST", new Bundle[]{appConfig});
      

      Parcelable array object with JavaScript:

      
          {"PROFILE_NAME": "Zebra Showcase", "PROFILE_ENABLED": "true", "CONFIG_MODE": "OVERWRITE", "APP_LIST": [{ "PACKAGE_NAME": "com.zebra.mdna.enterprisebrowser", "ACTIVITY_LIST": ["com.rhomobile.rhodes.RhodesActivity"] }
          ]}
      

      Parcelable array list with Java:

      
          Bundle bMain = new Bundle();
          ArrayList bundlePluginConfig = new ArrayList<>();
          Bundle bConfigWorkflow = new Bundle();
          bConfigWorkflow.putString("PLUGIN_NAME", "WORKFLOW");
          bConfigWorkflow.putString("RESET_CONFIG", "true");
          bundlePluginConfig.add(bConfigWorkflow);
          Bundle bConfigIntent = new Bundle();
          bConfigIntent.putString("PLUGIN_NAME", "INTENT");
          bConfigIntent.putString("RESET_CONFIG", "true"); //Reset existing configurations of intent output plugin
          bParamsIntent.putString("intent_output_enabled", "true");
          bundlePluginConfig.add(bConfigIntent);
          bMain.putParcelableArrayList("PLUGIN_CONFIG", bundlePluginConfig);
      

      Parcelable array list with JavaScript:

      
          {"PLUGIN_CONFIG":[[
          {"PLUGIN_NAME": "WORKFLOW", "RESET_CONFIG":"true"}
          ],[{"PLUGIN_NAME": "INTENT", "RESET_CONFIG": "true", "intent_output_enabled" : "true"}]]}