This package has been deprecated

    Author message:

    The snowplow-tracker-core package is now deprecated. Please switch to @snowplow/tracker-core

    snowplow-tracker-core
    TypeScript icon, indicating that this package has built-in type declarations

    0.10.0 • Public • Published

    Snowplow JavaScript Tracker Core

    npm version

    Core module to be used by Snowplow JavaScript based trackers.

    Developer quick start

    Can be built, tested and packed locally directly with Node (10+) and npm.

    Use npm install, npm run build, npm run test and npm pack

    Below instructions assume git and Docker installed.

    Clone repository

    host$ git clone https://github.com/snowplow/snowplow-javascript-tracker.git

    Building Tracker Core

    host$ cd snowplow-javascript-tracker/core
    host$ docker build -t core .
    host$ docker run -v "$(pwd)":"/code" core npm run build

    Running tests

    host$ docker run core npm run test

    Create NPM Package locally

    host$ docker run -v "$(pwd)":"/code" core npm pack

    For testing, the resulting tarball snowplow-tracker-core-x.x.x.tgz can be installed locally into another application (such as the Snowplow JavaScript Tracker).

    host$ npm install snowplow-tracker-core-x.x.x.tgz

    Installation

    With npm:

    npm install snowplow-tracker-core

    CommonJS Example

    const trackerCore = require('snowplow-tracker-core').trackerCore;
    
    // Create an instance with base 64 encoding set to false (it defaults to true)
    const core = trackerCore(false);

    ES Module Example

    import { trackerCore } from 'snowplow-tracker-core';
    
    // Create an instance with base 64 encoding set to false (it defaults to true)
    const core = trackerCore(false)

    Example

    // Add a name-value pair to all payloads
    core.addPayloadPair('vid', 2);
    
    // Add each name-value pair in a dictionary to all payloads
    core.addPayloadDict({
        'ds': '1160x620',
        'fp': 4070134789
    });
    
    // Add name-value pairs to all payloads using convenience methods
    core.setTrackerVersion('js-3.0.0');
    core.setPlatform('web');
    core.setUserId('user-321');
    core.setColorDepth(24);
    core.setViewport(600, 400);
    core.setUseragent('Snowplow/0.0.1');
    
    // Track a page view with URL and title
    const pageViewPayload = core.trackPageView('http://www.example.com', 'landing page');
    
    console.log(pageViewPayload.build());
    /*
    {
        'e': 'pv',
        'url': 'http://www.example.com',
        'page': 'landing page',
        'uid': 'user-321',
        'vd': 2,
        'ds': '1160x620',
        'fp': 4070134789
        'tv': 'js-3.0.0',
        'p': 'web',
        'cd': 24,
        'vp': '600x400',
        'ua': 'Snowplow/0.0.1',
        'dtm': 1406879959702,                          // timestamp
        'eid': '0718a85a-45dc-4f71-a949-27870442ed7d'  // UUID
    }
    */
    
    // Stop automatically adding tv, p, and dtm to the payload
    core.resetPayloadPairs();
    
    // Track an unstructured event
    const unstructEventPayload = core.trackUnstructEvent({
        'schema': 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-0',
        'data': {
            'targetUrl': 'http://www.destination.com',
            'elementId': 'bannerLink'
        }
    });
    
    console.log(unstructEventPayload.build());
    /*
    {
        'e': 'ue',
        'ue_pr': {
            'schema': 'iglu:com.snowplowanalytics.snowplow/unstruct_even/jsonschema/1-0-0',
            'data': {
                'schema': 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-0',
                'data': {
                    'targetUrl': 'http://www.destination.com',
                    'elementId': 'bannerLink'
                }
            }
        },
        'dtm': 1406879973439,
        'eid': '956c6670-cbf6-460b-9f96-143e0320fdf6'
    }
    */

    Other features

    Core instances can be initialized with two parameters. The first is a boolean and determines whether custom contexts and unstructured events will be base 64 encoded. The second is an optional callback function which gets applied to every payload created by the instance.

    const core = trackerCore(true, console.log);

    The above example would base 64 encode all unstructured events and custom contexts and would log each payload to the console.

    Use the setBase64Encoding method to turn base 64 encoding on or off after initializing a core instance:

    const core = trackerCore(); // Base 64 encoding on by default
    
    core.setBase64Encoding(false); // Base 64 encoding is now off

    Documentation

    For more information on the Snowplow JavaScript Tracker Core's API, view its wiki page.

    Copyright and license

    The Snowplow JavaScript Tracker Core is copyright 2014-2020 Snowplow Analytics Ltd.

    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

    Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

    Install

    npm i snowplow-tracker-core

    DownloadsWeekly Downloads

    9,579

    Version

    0.10.0

    License

    Apache-2.0

    Unpacked Size

    361 kB

    Total Files

    9

    Last publish

    Collaborators

    • cogsp
    • paul_boocock
    • snowplow-analytics