npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

inbound

v0.0.6

Published

Url referrer and campaign parsing utilities

Downloads

1,288

Readme

inbound


inbound is a referrer parsing library for node.js / express web apps.

How To Use

Install

npm install inbound

API

var inbound = require('inbound');
inbound.referrer.parse(url, referrer, function (err, description) {
    console.log(description);
});

url (string) is the page url, equivalent to client-side javascript's window.location.href or express.js req.url

referrer (string) is the referrer, equivalent to client-side javascript's document.referrer or express.js req.header('referrer')

Express.js Middleware

var inbound = require('inbound'),
    express = require('express');

var app = express();

app.use(function (req, res, next) {
  var referrer = req.header('referrer');
  var href = req.url;
  inbound.referrer.parse(href, referrer, function (err, desc) {
    req.referrer = desc;
    next(err);
  });
});

app.use(app.router);

app.get('/', function (req, res, next) {
  return res.send(req.referrer);
});

var port = 8000;
app.listen(port);
console.log('Server listening on port : ' + port);

Examples

Here is an example of a visitor clicking a twitter link and ending up at a New Yorker article.

var url = "http://www.newyorker.com/online/blogs/johncassidy/2012/08/economy-points-to-dead-heat-in-november.html?
mbid=gnep&google_editors_picks=true";
var referrer = "http://twitter.com/ryah";

inbound.referrer.parse(url, referrer, function (err, description) {
    console.log(description);
});
{
  "referrer": {
    "type": "social",
    "network": "twitter"
  }
}

Here's an example of a visitor clicking a campaign email from gmail, and arriving at a blog:

var url = "http://blog.intercom.io/churn-retention-and-reengaging-customers/?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A+contrast%2Fblog+%28The+Intercom+Blog%29";
var referrer =  "https://mail.google.com/_/mail-static/_/js/main/m_i,t/rt=h/ver=am293eyFlXI.en./sv=1/am=!v8Czf-oeNMn1FOzaNKsLQrJy-oNN3RSSYMAZTBUxCzwgQcXtLnTEHCkGr437GpFE2Dliuw/d=1";

inbound.referrer.parse(url, referrer, function (err, description) {
    console.log(description);
});
{
  "referrer": {
     "type": "email",
     "client": "gmail",
     "from": "https://mail.google.com/_/mail-static/_/js/main/m_i,t/rt=h/ver=am293eyFlXI.en./sv=1/am=!v8Czf-oeNMn1FOzaNKsLQrJy-oNN3RSSYMAZTBUxCzwgQcXtLnTEHCkGr437GpFE2Dliuw/d=1",
     "link": "http://blog.intercom.io/churn-retention-and-reengaging-customers/?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A+contrast%2Fblog+%28The+Intercom+Blog%29"
  },
  "campaign": {
    "source": "feedburner",
    "medium": "feed",
    "campaign": "Feed: contrast/blog (The Intercom Blog)"
  }
}

Supported Matchers

Social

Search

Email Clients

Ads

Internal

Internal referrers occur when a visitor navigates between two pages of the same domain. Example: http://site.com => http://site.com/about

Link

If there is a referrer present but it's unrecognized above, we'll just call it a link referrer.

Direct

When a visitor navigates to a site by typing in the url into the address bar, document.referrer is blank. This is called a direct referral. (There are some other reasons this can happen as well.)

Utilities

Shorten API

If you want to count the number of people who came from a specific referrer, you might want to make the following map:

referrer => { set_of_visitors }

However, referrers and urls tend to have differences that don't really matter to you, but are slightly different.

Use the inbound.shorten API to make the referrers and domains unique.

inbound.shorten.url('https://segment.io/?imm_mid=094f89&cmp=em-npa-ug-nl-sep15-html')
// "segment.io"

inbound.shorten.url('http://ianstormtaylor.com/oocss-plus-sass-is-the-best-way-to-css/?utm_source=hackernewsletter&utm_medium=email')
// "ianstormtaylor.com/oocss-plus-sass-is-the-best-way-to-css

Contribute

Contributors

Matchers

Matchers help identify and attach more semantic information to referral sources. We'd your help on adding the hundreds of social, search, ad, and other referral sources not matched yet by inbound.

To add matchers:

  1. Using existing matchers as an example, create your matcher at /lib/matchers/.
  2. Add your matcher to the priority list of matchers in index.js.
  3. Add your test cases to the test cases file.
  4. Run and confirm that your test cases pass: npm test
  5. Add your matcher to the readme.
  6. Submit your pull request!

Advanced

Why is my document.referrer blank?

  1. The visitor came directly to your site by typing the link into the browser's bar.
  2. The visitor clicked a link on an https:// page and arrived at a http:// page, such as clicking a link to http://hypem.com on a https://gmail.com email. (Chrome will strip the referrer since you're downgrading security).
  3. You were 301 redirected via a proxy that didn't maintain the referrer header.

Why is the matchers API asynchronous?

Even though most matchers do synchronous string matching, leaving the API asynchronous allows matchers that fill in more semantic information about the referrer by hitting some sort of API.

License

WWWWWW||WWWWWW
 W W W||W W W
      ||
    ( OO )__________
     /  |           \
    /o o|    MIT     \
    \___/||_||__||_|| *
         || ||  || ||
        _||_|| _||_||
       (__|__|(__|__|