Module: Tether Stats Author: Rustin Zantolas ================================================================================ Introduction ================================================================================ Collects site statistics from JS enabled users by using a JSON callback to track events. Essentially, an AJAX style call from the user is used to record activity, thus preventing most bots from polluting the data. Tether Stats is intended for intermediate to advanced Drupal developers. It behaves like a framework allowing you to relate site activity to your content structure using Drupal's entity concept. If you need to collect more data than what Google Analytics or Drupal stats can provide, this module may help fill in those gaps. The stats tables are relatively easy to mine and may be generated on a database separate from your Drupal core database. Here are the basic type of stats that Tether Stats collects: * Page Hits * Link Clicks * Impressions (An impression occurs when an item, such as a link, name or image, appears on a page and is made visible to the user.) It can be challenging to customize Google Analytics for Link Clicks or Impressions when Google knows nothing about your internal structure. Tether Stats can make collecting this type of data as simple as adding classes to your HMTL structure. ================================================================================ Recommended Modules ================================================================================ Tether Stats also provides a chart module which has classes for the generation of iterable charts based on collected data. Please refer to the README.txt file within the modules/tether_stats_charts directory. ================================================================================ Configuration ================================================================================ * Configure user permissions in Administration » People » Permissions: - The 'Administer Tether Stats' is required to update Tether Stats settings or use any of the administrative tools. * Configure settings for the Tether Stats module at admin/config/system/tether_stats ================================================================================ Concepts ================================================================================ Elements ======== Tether Stats simplifies its tables by converting every item for which activity is recorded to a stats "element." Elements may include module generated pages, any type of entity within Drupal including any unique custom entities you may have created, or an element of your own making with a unique name. You may also create elements derived from other elements for more flexibility. Basically, everything that stats are collected for will have an entry in the tether_stats_element tables, each having an elid or element id. This table is populated automatically as needed whenever a new event is requested to be tracked. Activity ======== When an event is tracked, an entry is added to the tether_stats_activity_log table. This entry will contain the elid of the element on which the event occurred as well as the standard information regarding the user that triggered the event. Impressions =========== When a user loads a tracking enabled page, a "hit" entry is added to the activity log to record that event. By adding classes to the HTML markup, you may request that other elements be impressed on that page. In this case, an entry is added to the tether_stats_impression_log for every element to be impressed. The impression log table is very simple as it only needs to relate the element to be impressed to the activity_log entry where the impression was made. ================================================================================ Identify Sets ================================================================================ Basic Sets ========== Other than the elid, elements are identified by so called "identify sets." This is a set of identifiers which Tether Stats can map uniquely to a specific element. The tether_stats_get_element function takes this set of identifiers and returns the matching element. If no entry for that element currently exists, one can be created. Excluding derivatives, an element may be identified by three possible combinations, a unique string name just for that element, an entity_id, or just by a url. Examples: By name, array( 'name' => 'my_unique_element_id', ) By entity, array( 'entity_type' => 'node', 'entity_id' => 1234, ) By url, array( 'url' => 'my_page/url', ) In the case of a module generated page which can only be identified by the url, the entry in the element table will populate the 'entity_type' field with the special 'tether_page' value. However, if the url only identify set was given for a node based page, the tether_stats_get_element function automically transform the identify set include the 'entity_type' and 'entity_id'. In this way, page elements can easily be looked up by their respective entities. Derivatives =========== There may be cases where data needs to be collected for things which are not entities or pages but are related. For example, suppose you have a link called "promotion" that appears on all your pages for a node type called "blog". You could create a uniquely named element to represent that link and then track it how many times it was clicked. This would group all the link clicks on all blog pages into one stat counter. This would only tell us how well the link is performing overall, but it would not indicate how the blogs are fairing individually. In this case, you can tell Tether Stats to create a different element for the promotion link on each of the blog pages. This is done by creating a "derivative." Each derivative has a unique string identifier and can be created for any type of stats element. For the above example, you could create the following derivative: array( 'entity_type' => 'node', 'entity_bundle' => 'blog', 'name' => 'link-promotion', 'description' => 'The promotion link on a blog page', ) Once this derivative is created, you can use the following identify set to refer to the link element on a blog page: array( 'entity_type' => 'node', 'entity_id' => 1234, 'derivative' => 'link-promotion', ) By adding this identify set to your link on each blog page, Tether Stats will create a new promotion link element for each blog page. Adding the 'derivative' field to the set now refers to an entirely new element with its own activity. The 'entity_type' and 'entity_bundle' properties of the derivative are optional and constrain this derivative so that it can only be applied to entity boung elements for node pages of type blog. Derivatives may be created and managed from admin/config/system/tether_stats/derivatives ================================================================================ How To Track Link Clicks ================================================================================ To track a link click, first add the class "tether_stats-track-link" to the anchor tag. This indicates that Tether Stats should track when this link is clicked. Secondly, add your identify set to the same HTML tag in the form of data-{$field}="{$value}". From the example borrowed from the "Derivatives" section above: My Promotion Link In this example, you would need to create the "link-promotion" derivative before any link clicks could be tracked. Note, Tether Stats will not record the link click if the page is excluded from tracking. ================================================================================ How To Track Impressions ================================================================================ To track an impression, first add the class "tether_stats-track-impress" to an HTML tag, most likely the tag that contains the things you want to impress. Secondly, add your identify set to the same HTML tag in the form of data-{$field}="{$value}" as you would for Link Clicks. For example, suppose you want to impress how many times a user has appeared on other pages. If you have a teaser that you use for your users, then you could add the class and attributes to that teaser.
This project has been sponsored by: * The American Society For Aesthetic Plastic Surgery This module is based on work done for the society's public website www.smartbeautyguide.com. They have benefited a lot from the Drupal Community and were pleased they could help give something back.