Snowplow Inspector Web Extension

A debugging tool to help you examine and debug your Snowplow tracking implementation.

Features

• List and filter all your tracking events

• See tracking parameters in human-friendly format

• GET and POST tracking support

• Automatically decode and parse Self-Describing Events and Custom Entities

• Validate your Entities and Events against the schemas in your Iglu Repository

• Import events from your bad rows bucket/stream and see why they failed enrichment

Feedback, feature requests, pull requests, and bug reports are welcome! Please file an issue.

Install

At the moment, only Chrome/Chromium are supported via an official app store, and builds for Firefox are available, but not supported. The extension also works in Microsoft Edge, but is not yet in the extension store. To install the extension, visit the page on the Chrome Web Store. You can get builds for Firefox v60+ in Releases.

Schema Validation

The Schema Manager inside the extension should let you load in local JSON Schema files during development, and you can also add your production or Snowplow Mini Iglu Repositories to test against what you have in production.

All of

• Local Registries (embedded into the extension)

• Static Iglu Repositories

• Iglu Servers (like the one used in Snowplow Mini)

• Data Structures API are supported.

Adding an Iglu Repository

1. Head to the extension pane in the Dev Tools, and hit the Manage Schemas button in the top toolbar

2. In the bottom right, hit Registries…​, then Add

3. Fill out the details for you new Registry and save

4. Note your browser will request permission for the Extension to access the registries' Domain, this may happen in the main browser window rather than the Dev Tools window if it’s not docked

5. You can also import your pipeline’s configuration using Import and supplying a resolver-config

By default we include the URL for Iglu Central, which includes schemas for the built-in tracking JSONs. You can add as many repositories as you like.

Importing from Ngrok Tunnels

The Ngrok Tunnel import uses an Ngrok tunnel in order to process events from remote devices. Ngrok provides a HTTP endpoint that we can use as the temporary collector endpoint.

By using this tunnel this allows you to test and debug events from additional devices and platforms including:

• A separate mobile device (using a native or React Native app)

• Server side events (e.g., server side Go codebase)

• IoT devices (smart watch, TVs)

• Any other device or implementation where you can override the Collector Endpoint

To start the tunnel ensure you have downloaded ngrok locally and create a new tunnel on the device you are running Chrome and the extension on, with:

$ ngrok http example.snplow.net

Where example.snplow.net is the Collector hostname that you wish to forward requests on to. This can be Micro, Mini or any other Snowplow Collector / server that responds with a 200.

Once your tunnel has started ngrok will return a HTTP/S url (under 'Forwarding') that you should then use as your Collector host. Events sent to this host will be intercepted by ngrok and forwarded to your Snowplow destination without modification.

In addition ngrok will create a Web Interface that runs on localhost (port 4040) by default. The API for this interface is used to retrieve events and insert them into the tool. If you wish to override or change this address you can do so in the options settings of the Chrome extension by right-clicking on the icon and opening Options.

If you wish to use a static address to forward to you can do so on one of the paid ngrok plans (a few dollars a month) to avoid having the hostname being dynamic.

To start visualizing these events open the debugger and select 'Import' then 'Ngrok Tunnel' which will begin to poll (via the Ngrok Agent API) for events.

To stop streaming these events select 'Import' then 'Stop Ngrok Tunnel'.

Develop

Build

1. Fork/clone this repo (git clone https://github.com/snowplow/chrome-snowplow-inspector.git)

2. Change to this directory (cd chrome-snowplow-inspector)

3. Run npm install to install required dependencies and build the extension in the dist/ directory

4. Load the created dist directory as an unpacked extension

More detailed instructions to install a local development version of the extension to test are over at the extension development documentation.

Hack

Once the unpacked extension is loaded, you can use npm start to start the build in "watch mode" to make updates easier; source changes should then be reflected in dist/ automatically.

You will need to close/reopen DevTools to see your changes.

If you intend to make a pull request, (thankyou!) please ensure npm test runs cleanly. This will check for type errors with the TypeScript compiler, and validate the code formatting. npm run fmt will reformat any changes to meet the formatting requirements.

To do a build without watch mode, npm install will automatically do npm run prepare, which does a normal build.

Watch-mode builds of the extension use the production extension identifier by default and talk to the production Console API; you can alter build.mjs to not do this if you want to isolate the extension environment from the production extension, or to work with a staging environment of the Snowplow Console (though most external contributors will not have login information). Likewise, to use the production ID with a non-watch build, (e.g. to distribute a modified unpacked build) modify build.mjs to not remove the key from manifest.json so a new one is generated.

Publishing

• npm run zip will produce a .zip file ready for uploading to the Chrome Web Store Developer Dashboard

• npm run xpi-signed will create a signed .xpi file for Firefox builds (this requires WEB_EXT_API_KEY and WEB_EXT_API_SECRET environment variables for signing; use just npm run xpi for an unsigned file)