Advanced topics
How to use the Javascript Collector for your node.js server-side environment
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.
1cd your_nodejs_app_directoryInstall the Datazoom Collector: Add the Datazoom App Collector and its xmlhttprequest dependency to your project using npm.
1npm install @datazoom/collector_app xmlhttprequestDownload 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:
1"dependencies": {2 "@datazoom/collector_app": "^2.1.0",3 "xmlhttprequest": "^1.8.0"4}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.
1node index.js YOUR_CONFIGURATION_IDReplace 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.
1// Add XMLHttpRequest support2global.XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;34// Add Datazoom base/app collector5const datazoom = require('@datazoom/collector_app');Setting Log Level (Optional)
You can enable verbose debug logging to help with troubleshooting during development.
1// Keep the following if verbose debug logging is desired2datazoom.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.
1const configurationID = process.argv[2]; // Or retrieve it from environment variables (e.g., process.env.DATAZOOM_CONFIG_ID), config files, etc.2if (!configurationID) {3 console.log("Missing Datazoom collector configuration ID");4 process.exit(-1);5}6// Initialize Datazoom collector7datazoom.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.
1const collectorContext1 = datazoom.createBaseContext(); // This context will have a default nameNamed Context
A context with a specific identifier, useful for tracking distinct entities or sessions.
1const 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.
1datazoom.setMetadata({2 deviceTag: "1234",3 someCount: 99,4 someOverwritableField: "A"5});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.
1collectorContext1.setMetadata({2 foo: "foofoo",3 someOverwritableField: "B" // Overwrites global 'someOverwritableField' for collectorContext14});5collectorContext2.setMetadata({6 bar: "barbar",7 someOverwritableField: "C" // Overwrites global 'someOverwritableField' for collectorContext28});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.
1datazoom.generateEvent("eventG");Context-Specific Custom Events
Events associated with a particular context.
1collectorContext1.generateEvent("eventC1");2collectorContext2.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.
1// Add XMLHttpRequest support2global.XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;34// Add Datazoom base/app collector5const datazoom = require('@datazoom/collector_app');67// Keep the following if verbose debug logging is desired8datazoom.setLogLevel("debug");910// Retrieve Configuration ID from command-line arguments11const configurationID = process.argv[2];12if (!configurationID) {13 console.log("Missing Datazoom collector configuration ID");14 process.exit(-1);15}1617// Initialize Datazoom collector18datazoom.init({ configuration_id: configurationID });1920// Create collector contexts21const collectorContext1 = datazoom.createBaseContext(); // unnamed context (will be assigned a default name)22const collectorContext2 = datazoom.createBaseContext({ contextName: "Joe" }); // named context2324// Set global custom metadata25datazoom.setMetadata({26 deviceTag: "1234",27 someCount: 99,28 someOverwritableField: "A"29});3031// Set context specific custom metadata32collectorContext1.setMetadata({33 foo: "foofoo",34 someOverwritableField: "B"35});36collectorContext2.setMetadata({37 bar: "barbar",38 someOverwritableField: "C"39});4041// Fire global custom event after 1 second42setTimeout(() => {43 datazoom.generateEvent("eventG");44}, 1000);4546// Fire context specific custom events after 2 and 3 seconds respectively47setTimeout(() => {48 collectorContext1.generateEvent("eventC1");49}, 2000);50setTimeout(() => {51 collectorContext2.generateEvent("eventC2");52}, 3000);5354// Exit the process after 5 seconds to allow events to be sent55setTimeout(() => {56 process.exit(0);57}, 5000);