@iloveme/referrer
v0.1.4
Published
Url referrer parser
Downloads
8
Readme
ilove.me Referrer
ilove.me Referrer is a referrer parsing library for node.js / express web apps. This is a fork of https://github.com/segmentio/inbound
How To Use
Install
npm install @iloveme/referrer
API
const ilmReferrer = require('@iloveme/referrer');
async function parse (url, referrer) {
const description = await ilmReferrer.referrer.parse(url, referrer);
console.log(description);
return 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
const ilmReferrer = require('@iloveme/referrer');
const express = require('express');
const app = express();
app.use((req, res, next) => {
const referrer = req.header('referrer');
const href = req.url;
try {
const description = await ilmReferrer.referrer.parse(href, referrer);
req.referrer = description;
next();
} catch (err) {
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.
const url = "http://www.newyorker.com/online/blogs/johncassidy/2012/08/economy-points-to-dead-heat-in-november.html?mbid=gnep&google_editors_picks=true";
const referrer = "http://twitter.com/ryah";
ilmReferrer.referrer.parse(url, referrer).then((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";
ilmReferrer.referrer.parse(url, referrer).then((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)"
}
}
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 ilmReferrer.shorten
API to make the referrers and domains unique.
ilmReferrer.shorten.url('https://segment.io/?imm_mid=094f89&cmp=em-npa-ug-nl-sep15-html')
// "segment.io"
ilmReferrer.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
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 ILM Referrer.
To add matchers:
- Using existing matchers as an example, create your matcher at /lib/matchers/.
- Add your matcher to the priority list of matchers in index.js.
- Add your test cases to the test cases file.
- Run and confirm that your test cases pass:
npm test
- Add your matcher to the readme.
- Submit your pull request!
Advanced
Why is my document.referrer blank?
- The visitor came directly to your site by typing the link into the browser's bar.
- 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).
- 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 \
\___/||_||__||_|| *
|| || || ||
_||_|| _||_||
(__|__|(__|__|