Skip to content

Web Extension for debugging Snowplow pixels.

License

Notifications You must be signed in to change notification settings

snowplow/chrome-snowplow-inspector

Repository files navigation

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

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.

ngrok

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

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

Instructions to install a local development version of the extension to test are over at the extension development documentation.

Hack

You can also use npm start to start rollup in watch mode to make editing easier; source changes should then be reflected in dist/. Some changes will automatically be reflected straight away, more intense changes will need to reopen DevTools to update correctly.