Sophi Data Inspector Web Extension

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

This is a customized version of the Poplin Data extension, tailored for users implementing Sophi products.

Install

Until complete and uploaded to the Chrome Web Store, you have to build and install the extension locally.

Build

1. Clone this repo

2. Install dependencies: npm install

3. Build the extension: npm run build

4. The built extension code should be created in a new dist folder

5. If you’re happy with the build, npm run zip will produce a .zip file suitable for uploading to the Chrome Web Store for distribution

Install Locally

1. Open Chrome

2. Head to the "Manage Extensions" page

   1. (typically, the dots menu > More tools > Extensions).

3. Enable "Developer mode" using the toggle in the top right corner

4. A toolbar should appear that includes a "Load unpacked"

5. Click "Load unpacked", and navigate to the dist directory created from the build

6. The extension should ask for required permissions and install

7. Navigate to a site with Sophi implemented, open the Dev Tools

8. There should be a Sophi.io tab that activates the extension

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.

Configuration API

Unique to this version of the extension is the concept of a configuration key.

The key is a secret UUID that is used to retrieve a customer-specific configuration.

Once enabled (planned for v2), upon first open, the extension will ask the user to supply their configuration key.

It will not become interactive until a valid key is supplied; the key can be changed or removed in the extension Options.

Once provided, the key is used to make a GET request to the API endpoint (defined by setting the CONFIG_ENDPOINT) at build time.

The API needs to return a JSON document containing the configuration for the corresponding key.

For example:

• during development the value from .env.development defines CONFIG_ENDPOINT to http://localhost:8000/sophiconfig

• the user starts the extension, is prompted for a configuration key

• the user supplies the key provided to them by Sophi (e.g. 6b49b558-cbea-4254-9014-ff97281ea01d)

• the extension makes a request to http://localhost:8000/sophiconfig/6b49b558-cbea-4254-9014-ff97281ea01d

• the API returns the following config:

{
  "key": "6b49b558-cbea-4254-9014-ff97281ea01d",
  "active": true,
  "client": "Test Client",
  "registries": [{
    "kind": "iglu",
    "name": "Sophi.io Iglu Registry",
    "uri": "https://sophi-example.iglu.snplow.net/api",
    "apiKey": "11111111-2222-3333-4444-555555555555"
  }],
  "products": ["paywall"],
  "custom": {
    "params": {"APP_ID": "example.com"}
  }
}

• the extension verifies the config is valid and active is true

• the extension saves the config key to storage for future use

• the extension loads any registries defined in the configuration

• the extension enables the built-in test suites for each named product in the products list

• the prompt disappears and the extension becomes interactive

On subsequent opens, the extension will see the saved configuration key, and automatically request and validate the configuration upon first loading. If the config value becomes inactive ("active": false) or the API doesn’t provide a valid config, the extension will ask the user for a new key.

The API format is intended to be simple to enable simple deployment (e.g. a static S3 bucket would work fine).

Security isn’t a huge consideration for protecting the config, relying on the obscurity provided by the entropy of UUIDs.

For development purposes, you can save JSON files and host them locally quite simply. For example:

$ mkdir -p config/sophiconfig
$ touch config/sophiconfig/6b49b558-cbea-4254-9014-ff97281ea01d
$ # save your config JSON into config/sophiconfig/6b49b558-cbea-4254-9014-ff97281ea01d
$ python3 -m http.server -d config &

This will serve the config directory and any files under it under http://localhost:8000, so when the extension requests a config it will load the local file.

Prior to publishing v2 of the extension, the actual API endpoint will need to be specified (likely in a .env.production file or similar).

Develop

You can also use npm start to start parcel in watch mode and symlink the resources to make editing easier; source changes should then be reflected immediately in dist/. You may still need to reload the extension in a browser.