Last week, we open sourced Sherlock, a pluggable tool for detecting third-party services on a given web page. You might use this to detect analytics trackers (eg: Google Analytics, Mixpanel, etc.), or social media widgets (eg: Facebook, Twitter, etc.) on your site.

Sherlock at Segment

We know that setting up your integrations has required some manual work. You’ve had to gather all your API keys and enter them into your Segment project one by one. We wanted to make this process easier for you, and thought that a “detective” to find your existing integrations would help!

Enter Sherlock. When you tell us your project’s url, Sherlock searches through your web page and finds the integrations you’re already using. Then, he automatically enters your integrations’ settings, which makes turning on new tools a bit easier.

How It Works

Here’s a code sample of Sherlock in action:

var Sherlock = require('sherlock-inspector');

var twitter = {
  name: 'Twitter Widget',
  script: 'https://platform.twitter.com/widgets.js'
};

var url = 'https://segment.com/blog/introducing-sherlock/';

Sherlock()
  .use(twitter)
  .analyze(url, function (err, results) {
    // results = { 'Twitter Widget': true }
  });

Since there are no services baked into Sherlock itself, we’re adding a Twitter plugin here manually. Sherlock opens the url and if widgets.js is present on the page, then it will be added to results.

The above example is admittedly trivial. Here’s a more realistic use-case:

var Sherlock = require('sherlock-inspector');
var segment = require('sherlock-segment');

var url = 'http://segmentio.github.io/sherlock-segment/demo.html';

Sherlock()
  .use(segment)
  .analyze(url, function (err, results) {
    // ...
  });

Here, we are adding sherlock-segment, a collection of plugins for about 20 of the integrations on our platform. Now, results will look like this:

{
  "Amplitude": {
    "apiKey": "0123456789abcdef0123456789abcdef"
  },
  "Google Analytics": {
    "trackingId": "UA-123456789-0"
  },
  "KISSmetrics": {
    "apiKey": "0123456789abcdef0123456789abcdef01234567"
  },
  "Mixpanel": {
    "token": "0123456789abcdef0123456789abcdef",
    "people": false,
    "trackAllPages": true,
    "trackCategorizedPages": false,
    "trackNamedPages": true
  }
}

Custom Plugins

To make your own plugin, simply add the following details to your package.json: (feel free to use sherlock-segment as a starting point)

  • name should include “sherlock-“ as a prefix

  • keywords should include “sherlock”

Your plugin should export an array of service configuration objects, each object can support the following keys:

  • name should be a human-readable string

  • script can be a string, regular expression, or a function that matches the src attribute of a script tag

  • settings is an optional function that is run on the page to extract configuration

Here is an example service configuration:

var service = {
  name: 'FullStory',
  script: 'https://www.fullstory.com/s/fs.js',
  settings: function () {
    return { org: window._fs_org };
  }
};

Contributing

Our plugin currently supports about 20 integrations. If you are interested in helping us support even more, feel free to open up an issue or a PR on GitHub!