This document provides instructions and examples for integrating Datazoom's Javascript Collector with your node.js server-side environment and instrumenting custom events and metadata for collection.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js
Npm

Setup & Installation

Navigate to your project directory: Open your terminal or command prompt and change to the directory of your Node.js application.

cd your_nodejs_app_directory

Install the Datazoom Collector: Add the Datazoom App Collector and its xmlhttprequest dependency to your project using npm.

npm install @datazoom/collector_app xmlhttprequest

Download and add the necessary packages to your node_modules directory and update your package.json file. Your package.json dependencies section should look similar to this:

"dependencies": {
  "@datazoom/collector_app": "^2.1.0",
  "xmlhttprequest": "^1.8.0"
}

To run your Node.js application with the Datazoom collector, you'll typically execute your main script file (e.g., index.js) with Node.js, providing your Datazoom Configuration ID as a command-line argument.

node index.js YOUR_CONFIGURATION_ID

Replace YOUR_CONFIGURATION_ID with the actual Configuration ID provided by Datazoom. This ID is crucial for linking the data sent by the collector to your specific configuration on the Datazoom platform.

Usage

The following sections detail how to initialize and use the Datazoom Node.js Collector in your Node.js code.

Requiring Dependencies

First, you need to include the xmlhttprequest module for network communication and the @datazoom/collector_app module. The xmlhttprequest library is used to provide XMLHttpRequest functionality in the Node.js environment, which the collector leverages for sending data, similar to how it would operate in a browser.

// Add XMLHttpRequest support
global.XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;

// Add Datazoom base/app collector
const datazoom = require('@datazoom/collector_app');

Setting Log Level (Optional)

You can enable verbose debug logging to help with troubleshooting during development.

// Keep the following if verbose debug logging is desired
datazoom.setLogLevel("debug");

Initialization

Initialize the Datazoom collector with your unique configuration_id. This step is essential for the collector to communicate with the Datazoom platform.

const configurationID = process.argv[2]; // Or retrieve it from environment variables (e.g., process.env.DATAZOOM_CONFIG_ID), config files, etc.
if (!configurationID) {
  console.log("Missing Datazoom collector configuration ID");
  process.exit(-1);
}
// Initialize Datazoom collector
datazoom.init({ configuration_id: configurationID });

Creating Collector Contexts

Collector contexts allow you to segment or categorize the data you send. You can create multiple contexts.

Unnamed Context

When no contextName is provided, the context is automatically assigned a default name by Datazoom.

const collectorContext1 = datazoom.createBaseContext(); // This context will have a default name

Named Context

A context with a specific identifier, useful for tracking distinct entities or sessions.

const collectorContext2 = datazoom.createBaseContext({ contextName: "Joe" });

Setting Metadata

You can enrich your data with custom metadata at both global and context-specific levels.

Global Custom Metadata

This metadata applies to all events sent by the collector instance.

datazoom.setMetadata({
  deviceTag: "1234",
  someCount: 99,
  someOverwritableField: "A"
});

Context-Specific Custom Metadata

This metadata applies only to events generated by that particular context. If a field name is the same as a global metadata field, the context-specific value will overwrite the global value for events from that context.

collectorContext1.setMetadata({
  foo: "foofoo",
  someOverwritableField: "B" // Overwrites global 'someOverwritableField' for collectorContext1
});
collectorContext2.setMetadata({
  bar: "barbar",
  someOverwritableField: "C" // Overwrites global 'someOverwritableField' for collectorContext2
});

Generating Custom Events

You can send custom events to track specific occurrences within your application.

Global Custom Event

An event not tied to a specific context.

datazoom.generateEvent("eventG");

Context-Specific Custom Events

Events associated with a particular context.

collectorContext1.generateEvent("eventC1");
collectorContext2.generateEvent("eventC2");

Example index.js

This example initializes the collector, sets up global and context-specific metadata, and then fires a series of global and context-specific events with delays to simulate an application's lifecycle. The setTimeout calls for process.exit(0) ensure the script doesn't terminate before the events have a chance to be dispatched.

// Add XMLHttpRequest support
global.XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;

// Add Datazoom base/app collector
const datazoom = require('@datazoom/collector_app');

// Keep the following if verbose debug logging is desired
datazoom.setLogLevel("debug");

// Retrieve Configuration ID from command-line arguments
const configurationID = process.argv[2];
if (!configurationID) {
  console.log("Missing Datazoom collector configuration ID");
  process.exit(-1);
}

// Initialize Datazoom collector
datazoom.init({ configuration_id: configurationID });

// Create collector contexts
const collectorContext1 = datazoom.createBaseContext(); // unnamed context (will be assigned a default name)
const collectorContext2 = datazoom.createBaseContext({ contextName: "Joe" }); // named context

// Set global custom metadata
datazoom.setMetadata({
  deviceTag: "1234",
  someCount: 99,
  someOverwritableField: "A"
});

// Set context specific custom metadata
collectorContext1.setMetadata({
  foo: "foofoo",
  someOverwritableField: "B"
});
collectorContext2.setMetadata({
  bar: "barbar",
  someOverwritableField: "C"
});

// Fire global custom event after 1 second
setTimeout(() => {
  datazoom.generateEvent("eventG");
}, 1000);

// Fire context specific custom events after 2 and 3 seconds respectively
setTimeout(() => {
  collectorContext1.generateEvent("eventC1");
}, 2000);
setTimeout(() => {
  collectorContext2.generateEvent("eventC2");
}, 3000);

// Exit the process after 5 seconds to allow events to be sent
setTimeout(() => {
  process.exit(0);
}, 5000);