{"id":20977301,"url":"https://github.com/2degrees/event-nexus","last_synced_at":"2025-03-13T09:40:11.493Z","repository":{"id":5709612,"uuid":"6920545","full_name":"2degrees/event-nexus","owner":"2degrees","description":"Declarative binding for event recording","archived":false,"fork":false,"pushed_at":"2014-07-16T11:27:50.000Z","size":208,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-20T06:14:22.155Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/2degrees.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-11-29T12:11:14.000Z","updated_at":"2014-07-07T09:26:28.000Z","dependencies_parsed_at":"2022-08-30T10:30:32.306Z","dependency_job_id":null,"html_url":"https://github.com/2degrees/event-nexus","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2degrees%2Fevent-nexus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2degrees%2Fevent-nexus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2degrees%2Fevent-nexus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2degrees%2Fevent-nexus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/2degrees","download_url":"https://codeload.github.com/2degrees/event-nexus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243382155,"owners_count":20281998,"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":[],"created_at":"2024-11-19T04:58:13.922Z","updated_at":"2025-03-13T09:40:11.456Z","avatar_url":"https://github.com/2degrees.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# event-nexus\n\nA declarative way to tracking and recording events on your website.\n\n## Overview\n\nIf you need to set-up event tracking and recording on your website it can be\na never-ending task to keep lots of snippets of javascript up-to-date. With a\ndynamic site this becomes a task of ever-increasing complexity and maintenance\ncan become a headache.\n\nTo overcome this problem, `event-nexus` allows you to declare all the events\nyou want to track in a single place.\n\n## Adding the code to your site\n\n``event-nexus`` requires jQuery 1.7.2+ (it should work with any version of\njQuery 1.7). It is declared as an AMD-module so you can *require* it where you need it, and jQuery will be loaded for these modules.\n\n``event-nexus`` is broken down into three modules ``event_trackers``,\n``event_recorders`` and ``event_tracker_binding``. If you depend on all three modules,\ndo the following:\n\n``` javascript\nrequire(\n    ['event_trackers', 'event_recorders', 'event_tracker_binding'],\n    function (event_trackers, event_recorders, event_tracker_binding) {\n        // your code here\n    }\n);\n```\n\nIf you don't need all of the modules, they are completely independent so include just what you need to accomplish the task at hand.\n\n## Declaring your tracking configuration\n\n``event-nexus`` is designed to allow a declarative configuration of things to track.\nConsider a case where you want to track an impression of an advert on your site and\nalso a click on that advert.\n\nWe would define this as follows (e.g. in ``event_tracker_config.js``):\n\n``` javascript\ndefine(['event_trackers'], function (event_trackers) {\n    'use strict';\n\n    var EVENT_TRACKING_CONFIGURATION = [\n        // Advert impressions\n        {\n            event_tracker: new event_trackers.ElementImpressionTracker(\n                '.advert',\n                {\n                    category: 'Adverts',\n                    action: 'Impression of advert',\n                    label: function ($element) {\n                        return $element.data('advertiser');\n                    }\n                }\n            ),\n            page_ids: ['homepage', 'contact']\n        },\n        // Advert click-throughs\n        {\n            event_tracker: new event_trackers.OutboundLinkTracker(\n                '.advert\u003ea',\n                {\n                    category: 'Adverts',\n                    action: 'Click-through on advert',\n                    label: function ($element) {\n                        return $element.parent().data('advertiser');\n                    }\n                }\n            ),\n            page_ids: ['homepage', 'contact']\n        }\n    ];\n\n    return EVENT_TRACKING_CONFIGURATION;\n\n});\n```\n\nEach directive to track an event requires two parameters:\n\n* ``event_tracker``\n* ``page_ids``\n\n### event_tracker\n\nThis defines the objects which deals with tracking the browser event.\n``event-nexus`` comes with two main types:\n\n* user-interaction events (e.g. click event)\n* element impression (i.e. page load)\n\nIn the example above, we define one of each of these. Both trackers take two\narguments:\n\n1. The CSS selector which describes the element\n2. An object containing the data to track\n\nSince ``event-nexus`` relies on jQuery, any valid jQuery selector can be used to\ndescribe the element and can point to multiple similar elements on the page.\n\nThe data you track can be anything. This is largely governed by the event recorder\n([see below](#recording-events)) you choose to use. The values in the\nobject can either be strings or functions. When the function is called,\nit will receive the element as a jQuery object on which the event is taking place.\n\n#### A note on links\n\nSome analytics services cannot respond quickly enough to the browser's request before\nthe location changes when the click on a link is being recorded. To work around this,\nthe ``OutboundLinkTracker`` is available. This adds a short delay before directing the\nuser on to the next page, which should give most tracking services enough time to complete\ntheir work before the browser aborts that request.\n\nBe careful if you have other events bound on to the click as there may be some undesirable\nconsequences.\n\n### page_ids\n\nIf you have a lot of events to track on your site you want to make sure that you\ndon't see slow-down on all the pages due to a large configuration, you\ncan specify an identifier for the current page when parsing the configuration\n([see below](#recording-events)) which will be checked against the\nwhite-list provided in the event-tracker definition.\n\nIn the example given above, only the pages identified as *homepage* and *contact* will\nbe considered for having the specified events tracked on.\n\n**NB**: In debug mode ``event-nexus`` will warn you in the console if expected\nelements are missing and let you know when they are found.\n\n### Defining new event trackers\n\nIf you want to track another type of interaction, you can define\na new event tracker. The constructor can take anything you like,\nbut most likely will take some kind of tracking data.\n\nThen you need to define a ``bind`` method. This must receive the\n``tracking_data_handler``. This is a function which the event\nbinding system uses to link the tracker and the recorder together.\nYou simply need to call this function with your tracking data.\n\nFor more information, view the source!\n\n#### Browser event handlers\n\nIf all you want to do it track a pre-defined or custom browser event \nhandler, then the ``event_trackers`` module provides a factory to \ncreate such objects. Let's say we want to track a ``change`` event:\n\n``` javascript\nrequire(['event_trackers'], function (event_trackers) {\n    'use strict';\n    var ChangeTracker = event_trackers.build_specific_user_interaction_tracker('change');\n    var change_tracker = new ChangeTracker(element_selector, tracking_data);\n});\n```\n\n## Recording events\n\n``event-nexus`` ships with a simple console recorder which simply logs the resolved\ndata from the element to the browser console (if present).\n\nTo use this, set up tracking as follows:\n\n``` javascript\nrequire(\n    ['jquery', 'event_recorders', 'event_tracker_binding'],\n    function ($, event_recorders, event_tracker_binding) {\n        'use strict';\n\n        var event_recorder = new event_recorders.ConsoleEventRecorder();\n        event_tracker_binding.bind_trackers_to_dom(\n            EVENT_TRACKING_CONFIGURATION,\n            event_recorder,\n            $('html').data('page-id')\n        );\n    }\n);\n```\n\nNow you're ready to go and you'll start to see some events appearing\nin the console when you visit the *homepage* or the *contact* page.\n\n**NB**: This example also shows how you might pass the *Page ID* into the \ntracking system. This is left up to you so that you're not tied to\nany framework in particular.\n\n### Defining new event recorders\n\nHaving your events logged to the console is all well and good, but it's\nnot really going to give you much useful data. For this, you'll need to\nuse an event recording service such as [Google analytics](http://www.google.co.uk/analytics/).\n\nDefining a recorder to use with this service is straight-forward, e.g. in ``ga_recorder.js``:\n\n``` javascript\ndefine([], function () {\n    'use strict';\n\n    var GoogleAnalyticsEventRecorder = function () {};\n    GoogleAnalyticsEventRecorder.prototype = {\n        record: function (tracking_data) {\n            _gaq.push([\n                '_trackEvent',\n                tracking_data.category,\n                tracking_data.action,\n                tracking_data.label,\n                tracking_data.value,\n                !tracking_data.is_interactive // Google analytics requires \"non-interaction\"\n            ]);\n        }\n    };\n\n    return GoogleAnalyticsEventRecorder;\n});\n\n```\n\nAlthough ``event-nexus`` is essentially agnostic of the recording service\nyou might use, it was built with google analytics in mind, so you'll notice\nthat UserInteractionEventTracker updates the tracked data to set the ``is_interactive``\nflag to ``true`` and ElementImpressionTracker does the converse.\n\nYou can override these values by simply passing them in the data to track.\n\n## Running the tests\n\nThe test suite uses QUnit. Due to the paths declared for require.js, you need to run the web-server in the root of the repository, e.g.\n\n``` bash\ncd /path/to/event-nexus\npython -m SimpleHTTPServer\ngoogle-chrome http://localhost:8000/tests/test_runner.html\n```\n\n## Further info\n\nIf you're stuck on how to use the system take a look at the source or the tests\nas most use cases are covered there.\n\nFailing that, [get in touch](mailto:2degrees-floss@googlegroups.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2degrees%2Fevent-nexus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F2degrees%2Fevent-nexus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2degrees%2Fevent-nexus/lists"}