Skip to main content
Interania

Admin Guide: Configuring the Interana SDK for ingest

0votes
27updates
195views

This document demonstrates how to integrate the Interana SDK with a JavaScript Web application, so you can analyze the behavior of users that visit your site. 

See Streaming ingest to configure a live stream of data into Interana from a Web or cloud source with an HTTP API, see the Streaming ingest topic.

See Create a pipeline for an external Kafka cluster for information on how to configure a pipeline that connects to a particular Kafka broker (identified by its master zookeeper node) and consumes events on a particular Kafka topic.

 

 

 

SDK functions

The Interana SDK can be integrated into a JavaScript Web application, allowing you to send events to an API. The API stores the data it receives in a location and format that is then ingested by Interana for analysis.

In order to send information to an Interana instance using the SDK, the Interana instance must have a trusted CA certificate. For more information, see Replace a self-signed certificate.

Initialization

Use the following syntax:

init({endpoint, actor, [defaultProperties]})

Arguments

A JavaScript object that contains the following properties:

endpoint—Required: URL to which the API will send events. It should include topic as a URL parameter to determine which stream events should be sent to the API. Example: https://my.interana.com/track?topic=my_topic

actor—Required: ID of the entity whose behavior will be tracked.

defaultProperties—Optional: a JavaScript object of properties to be logged with each event that is sent; properties are typically strings, numbers, or arrays.

Example

interana.init({endpoint: 'https://my.interana.com/track?topic=my_topic', actor: 'user1'})

Sending an event

Use the following syntax to send an event:

track({event, properties}, [callback])

Arguments

There are two arguments, as described below.

properties

A set of properties is logged with each event, and must include the following:

  • The event name that is included under the key "event".
  • The "timestamp" which is automatically appended to the event by Interana. If you provide a timestamp, it will be overwritten.

If you want to provide a "timestamp", even though it is not recommended, you can call trackWithTimestamp and provide your own timestamp.

callback

This is an optional callback function that will be invoked once the track call is complete. This function is invoked with two parameters: (error, response) => {}.

interana.track({event: 'test-event', testProp: 'foo', id: count++}, (error, response) => {

     const responseHolder = document.getElementById('response-holder');

     responseHolder.innerHTML += JSON.stringify(response) + '<br>';

});

If the interana.track() call succeeds, then there is no response. In case of a failure, the callback's first argument contains the error details.

Using the SDK example

The example in this section demonstrates how to create an HTML example using the JavaScript SDK, and walks you through the necessary tasks:

  1. Create a table.
  2. Create a pipeline.
  3. Create a job.
  4. Initialize the SDK and create an onclick function.
1. Create a table

The first step is to create a table into which to store the data. The SDK requires that you specify a value for "actor", then automatically includes the event time in the "timestamp" column in a epoch milliseconds format.

The following example creates an event table named, "my_events", using the SDK defaults for shard key ("actor") and time column ("timestamp" in epoch milliseconds format):

ia table create event my_events actor timestamp milliseconds
2. Create a pipeline

The next step is to create a pipeline through which the data is transferred to the table you created in the previous step. If you don't specify a topic, the SDK automatically uses  "DEFAULT_TOPIC".

In the following example, the pipeline name is sdk_pipeline. The http_listener data source type must be specified, which requires a kafka_topic parameter. The DEFAULT_TOPIC the SDK is added automatically, if you do not specify a topic.

ia pipeline create sdk_pipeline my_events http_listener -p kafka_topic DEFAULT_TOPIC

For more information on creating pipelines and jobs, see Streaming ingest and the Interana CLI reference.

 
3. Create a job

With the table and pipeline in place, you can now create a job that schedules the ingest. The following example is for a job that is continuous yesterday today. There are no “dates” in kafka and http_listener pipelines, so you could also specify a job as: continuous today today.

ia job create sdk_pipeline continuous yesterday today 
4. Initialize the SDK and create an onclick function

Now you can initialize the SDK for your application. The following HTML example initializes the Interana SDK and creates an onclick function that allows you to track user (actor: userId) activity.

<html lang="en">
  <head>
    <title>Interana API Example</title>
    <meta charset="UTF-8"/>
    <script src="https://sdk.interana.com/interana-sdk.browser.min.js"></script>
  </head>
  <body>
    <h3>Hello,</h3>
    <p>Welcome to the Interana SDK</p>
    <br/>
    <!-- Example button to track -->
    <button id="sdk_click">Make Interana Event</button>
    <script>
      window.onload = function () {
        // example simple userId.
        var userId = 1;


        // initialize the Interana SDK with your interana instance listener node
        // and the actor which is the SDK required shard key.
        interana.init({endpoint: 'https://<interana_instance_hostname>/track', actor: userId });


        // create a basic onclick function
        document.getElementById('sdk_click').onclick = function () {
          // call the interana track function
          // with any extra information you want to add as a column in Interana
          interana.track({ event: 'example event', exampleColumn: 'sdk click' }, function(error) {});
        };
      };
    </script>
  </body>
</html>  

       

  • Was this article helpful?