{"id":15975800,"url":"https://github.com/melihmucuk/monkeys-referrer","last_synced_at":"2025-03-18T00:30:53.224Z","repository":{"id":70958738,"uuid":"138564958","full_name":"melihmucuk/monkeys-referrer","owner":"melihmucuk","description":"referrer parsing library for node.js / express web apps","archived":false,"fork":false,"pushed_at":"2018-06-25T08:57:43.000Z","size":26,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-28T06:03:19.608Z","etag":null,"topics":["express","header-parser","nodejs","referrer","referrer-tracking","tracking"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/melihmucuk.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-06-25T08:23:57.000Z","updated_at":"2022-04-25T21:13:05.000Z","dependencies_parsed_at":"2023-12-17T16:10:52.631Z","dependency_job_id":null,"html_url":"https://github.com/melihmucuk/monkeys-referrer","commit_stats":{"total_commits":5,"total_committers":2,"mean_commits":2.5,"dds":"0.19999999999999996","last_synced_commit":"d6492380f2ac7a0d837028cfaa91c578b1a5ecc3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melihmucuk%2Fmonkeys-referrer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melihmucuk%2Fmonkeys-referrer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melihmucuk%2Fmonkeys-referrer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melihmucuk%2Fmonkeys-referrer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/melihmucuk","download_url":"https://codeload.github.com/melihmucuk/monkeys-referrer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243893849,"owners_count":20364918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","header-parser","nodejs","referrer","referrer-tracking","tracking"],"created_at":"2024-10-07T22:05:12.769Z","updated_at":"2025-03-18T00:30:52.137Z","avatar_url":"https://github.com/melihmucuk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# # monkeys-referrer\n---------------\n\nmonkeys-referrer is a referrer parsing library for node.js / express web apps. This is forked from [inbound](https://github.com/segmentio/inbound) because of lack of maintenance.\n\n## How To Use\n\n### Install\n```\nnpm install monkeys-referrer --save\n```\n\n### API\n```javascript\nvar mreferrer = require('monkeys-referrer');\nmreferrer.referrer.parse(url, referrer, function (err, description) {\n    console.log(description);\n});\n```\n\n**url** (string) is the page url, equivalent to client-side javascript's ```window.location.href``` or express.js ```req.url```\n\n**referrer** (string) is the referrer, equivalent to client-side javascript's ```document.referrer``` or express.js ```req.header('referrer')```\n\n### Express.js Middleware\n```javascript\nvar mreferrer = require('monkeys-referrer'),\n    express = require('express');\n\nvar app = express();\n\napp.use(function (req, res, next) {\n  var referrer = req.header('referrer');\n  var href = req.url;\n  mreferrer.referrer.parse(href, referrer, function (err, desc) {\n    req.referrer = desc;\n    next(err);\n  });\n});\n\napp.use(app.router);\n\napp.get('/', function (req, res, next) {\n  return res.send(req.referrer);\n});\n\nvar port = 8000;\napp.listen(port);\nconsole.log('Server listening on port : ' + port);\n```\n\n## Examples\n\nHere is an  example of a visitor clicking a twitter link and ending up at a New Yorker article.\n\n```javascript\nvar url = \"http://www.newyorker.com/online/blogs/johncassidy/2012/08/economy-points-to-dead-heat-in-november.html?\nmbid=gnep\u0026google_editors_picks=true\";\nvar referrer = \"http://twitter.com/ryah\";\n\nmreferrer.referrer.parse(url, referrer, function (err, description) {\n    console.log(description);\n});\n```\n```json\n{\n  \"referrer\": {\n    \"type\": \"social\",\n    \"network\": \"twitter\"\n  }\n}\n```\n\nHere's an example of a visitor clicking a campaign email from gmail, and arriving at a blog:\n\n```javascript\nvar url = \"http://blog.intercom.io/churn-retention-and-reengaging-customers/?utm_source=feedburner\u0026utm_medium=feed\u0026utm_campaign=Feed%3A+contrast%2Fblog+%28The+Intercom+Blog%29\";\nvar 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\";\n\nmreferrer.referrer.parse(url, referrer, function (err, description) {\n    console.log(description);\n});\n```\n```json\n{\n  \"referrer\": {\n     \"type\": \"email\",\n     \"client\": \"gmail\",\n     \"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\",\n     \"link\": \"http://blog.intercom.io/churn-retention-and-reengaging-customers/?utm_source=feedburner\u0026utm_medium=feed\u0026utm_campaign=Feed%3A+contrast%2Fblog+%28The+Intercom+Blog%29\"\n  },\n  \"campaign\": {\n    \"source\": \"feedburner\",\n    \"medium\": \"feed\",\n    \"campaign\": \"Feed: contrast/blog (The Intercom Blog)\"\n  }\n}\n```\n\n## Supported Matchers\n\n### Social\n* [Facebook](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/facebook.js)\n* [Instagram](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/instagram.js)\n* [Twitter](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/twitter.js)\n* [Medium](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/medium.js)\n* [Youtube](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/youtube.js)\n* [Google+](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/googlePlus.js)\n* [Pinterest](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/pinterest.js)\n* [LinkedIn](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/linkedin.js)\n* [Me2day](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/social/me2day.js)\n\n### Growth\n* [Reddit](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/growth/reddit.js)\n* [HackerNews](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/growth/hackernews.js)\n* [ProductHunt](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/growth/producthunt.js)\n* [Quora](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/growth/quora.js)\n* [IndieHackers](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/growth/indiehackers.js)\n\n### Search\n* [Google](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/google.js)\n* [Bing](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/bing.js)\n* [Yahoo](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/yahoo.js)\n* [Baidu](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/baidu.js)\n* [Yandex](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/yandex.js)\n* [Naver](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/naver.js)\n* [Daum](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/daum.js)\n* [Nate](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/search/nate.js)\n\n### Email Clients\n* [Gmail](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/email/gmail.js)\n* [Yahoo](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/email/yahoo.js)\n* [Hotmail](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/email/hotmail.js)\n* [Naver](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/email/naver.js)\n* [Daum](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/email/daum.js)\n\n### Ads\n* [Bing](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/ad/bing.js)\n* [Google](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/ad/google.js)\n* [Yahoo](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/ad/yahoo.js)\n\n### Internal\nInternal referrers occur when a visitor navigates between two pages of the same domain. Example: http://site.com =\u003e http://site.com/about\n\n* [Internal](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/internal/internal.js)\n\n### Link\nIf there is a referrer present but it's unrecognized above, we'll just call it a link referrer.\n\n* [Link](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/link/link.js)\n\n### Direct\nWhen 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](#why-is-my-documentreferrer-blank) this can happen as well.)\n\n* [Direct](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/direct/direct.js)\n\n## Utilities\n\n### Shorten API\n\nIf you want to count the number of people who came from a specific referrer, you might want to make the following map:\n\n```referrer =\u003e { set_of_visitors }```\n\nHowever, referrers and urls tend to have differences that don't really matter to you, but are slightly different.\n\nUse the `monkeys-referrer.shorten` API to make the referrers and domains unique.\n\n```javascript\nmreferrer shorten.url('https://segment.io/?imm_mid=094f89\u0026cmp=em-npa-ug-nl-sep15-html')\n// \"segment.io\"\n\nmreferrer.shorten.url('http://ianstormtaylor.com/oocss-plus-sass-is-the-best-way-to-css/?utm_source=hackernewsletter\u0026utm_medium=email')\n// \"ianstormtaylor.com/oocss-plus-sass-is-the-best-way-to-css\n```\n\n## Contribute\n\n### Matchers\nMatchers 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 monkeys-referrer.\n\nTo add matchers:\n\n1. Using existing matchers as an example, create your matcher at [/lib/matchers/](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/).\n1. Add your matcher to the priority list of matchers in [index.js](https://github.com/melihmucuk/monkeys-referrer/tree/master/lib/matchers/index.js).\n1. Add your test cases to [the test cases file](https://github.com/melihmucuk/monkeys-referrer/tree/master/test/cases/referrers.json).\n1. Run and confirm that your test cases pass: ```npm test```\n1. Add your matcher to the [readme](https://github.com/melihmucuk/monkeys-referrer/tree/master/README.md).\n1. Submit your pull request!\n\n## Advanced\n\n### Why is my document.referrer blank?\n1. The visitor came directly to your site by typing the link into the browser's bar.\n2. 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).\n3. You were 301 redirected via a proxy that didn't maintain the referrer header.\n\n### Why is the matchers API asynchronous?\n\nEven 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.\n\n## License\n\n\n```\nWWWWWW||WWWWWW\n W W W||W W W\n      ||\n    ( OO )__________\n     /  |           \\\n    /o o|    MIT     \\\n    \\___/||_||__||_|| *\n         || ||  || ||\n        _||_|| _||_||\n       (__|__|(__|__|\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelihmucuk%2Fmonkeys-referrer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmelihmucuk%2Fmonkeys-referrer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelihmucuk%2Fmonkeys-referrer/lists"}