Difference between revisions of "How to configure ContentMetrics"

From EtherWiki
Jump to: navigation, search
(Configuring the source web site)
m (Exclude visit count and current visitor)
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[ContentMetrics]] is added to a web site by configuring a ContentMetrics (CM) server and then registering the source web site that will communicate with the CM server.
+
[[ContentMetrics]] is added to a web site by configuring a ContentMetrics (CM) server, registering the source web site that will communicate with the CM server, and configuring pages from the source web site to communicate to the CM server.
 +
 
 +
* ContentMetrics (CM) server - a server that records visits and voting for any number of source web sites
 +
* Source web site - a web site that will send metrics to a single CM server
  
 
== Configuring the ContentMetrics server ==
 
== Configuring the ContentMetrics server ==
Line 7: Line 10:
 
* http://www.scottdstrader.com/cm/
 
* http://www.scottdstrader.com/cm/
  
The source web site must be registered with a user profile name (<code>'''%PROFILE-NAME%'''</code>) and host name (<code>'''%HOST-NAME%'''</code>).
+
The source web site must be registered with a user profile name (<code>'''%PROFILE-NAME%'''</code>) and host name (<code>'''%HOST-NAME%'''</code>). The <code>'''%PROFILE-NAME%'''</code> is an arbitrary and unique name that identifies the owner of one or more source web sites being tracked by ContentMetrics. The <code>'''%HOST-NAME%'''</code> is the actual [http://en.wikipedia.org/wiki/Hostname hostname] of the source web site with prefixes and suffixes (such as <code>www.</code> or <code>.com</code>) removed.
  
 
== Configuring the source web site ==
 
== Configuring the source web site ==
  
The following style sheet and two JavaScript file must be added to the <code><head></code> section of any page that will communication with the CM server:
+
The following style sheet and two JavaScript files must be added to the <code><head></code> section of any page that will communication with a CM server:
  
 
  <link rel="stylesheet" type="text/css" media="screen"
 
  <link rel="stylesheet" type="text/css" media="screen"
Line 20: Line 23:
 
     src="'''%CM-SERVER%'''/javascript/cm.js"></script>
 
     src="'''%CM-SERVER%'''/javascript/cm.js"></script>
  
With these entries added, any number of regions can be added to the page. Each region will track metrics for that region and display configurable results. The result will display wherever the script is placed on the page. Here is the basic format of the region script:
+
With these entries added, any number of '''regions''' can be added to the page. Each region will track metrics for that region alone and will display configurable results. The results will display wherever the script is placed on the page. Here is the basic format of the region script:
  
 
  <script type="text/javascript"
 
  <script type="text/javascript"
     src="'''%CM-SERVER%'''/region_create.php?id='''%PROFILE-NAME%'''&region='''%REGION-ID%'''&actions='''%ACTIONS%'''&metrics='''%METRICS%'''">
+
     src="'''%CM-SERVER%'''/region_create.php?id='''%PROFILE-NAME%'''&region='''%REGION-ID%'''&votes='''%VOTES%'''&actions='''%ACTIONS%'''&metrics='''%METRICS%'''">
 
  </script>
 
  </script>
  
[[Image:cm-region.png|thumb|An example of a region script displaying all metrics]]
+
Any number of individual regions can be added to a single page.
 +
 
 +
[[Image:cm-region.png|thumb|An example of a region script displaying the metrics 111,10111,1111]]
  
 
The following values are required:
 
The following values are required:
Line 32: Line 37:
 
* <code>'''%CM-SERVER%'''</code> and <code>'''%PROFILE-NAME%'''</code> - The CM server that will track the data under the profile registered on that server
 
* <code>'''%CM-SERVER%'''</code> and <code>'''%PROFILE-NAME%'''</code> - The CM server that will track the data under the profile registered on that server
 
* <code>'''%REGION-ID%'''</code> - A unique value within the registered <code>'''%HOST-NAME%'''</code>
 
* <code>'''%REGION-ID%'''</code> - A unique value within the registered <code>'''%HOST-NAME%'''</code>
 +
* <code>'''%VOTES%'''</code> - A comma-delimited pair of maximum up- and down-votes:
 +
 +
<table class="wikitable">
 +
<tr>
 +
<th>Value (position)</th><th>Description</th>
 +
</tr>
 +
<tr>
 +
<td>N,0</td><td>(default: 1) Maximum positive vote value. If 1, then an up-arrow is displayed. If &gt;1, then N number of right-pointing carets are displayed.</td>
 +
</tr>
 +
<tr>
 +
<td>0,N</td><td>(default: -1) Maximum negative vote value. If -1, then an down-arrow is displayed. If &lt;-1, then N number of left-pointing carets are displayed.</td>
 +
</tr>
 +
</table>
 +
 
* <code>'''%ACTIONS%'''</code> - A [http://en.wikipedia.org/wiki/Mask_(computing) bit mask] of allowable actions for this view of the reigon:
 
* <code>'''%ACTIONS%'''</code> - A [http://en.wikipedia.org/wiki/Mask_(computing) bit mask] of allowable actions for this view of the reigon:
  
Line 39: Line 58:
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>100 (1)</td><td>Record each visit. Turn off to use the region only for displaying metrics and voting on the content.</td>
+
<td></td><td>User actions:</td>
 +
</tr>
 +
<tr>
 +
<td>100,00</td><td>Record each visit. Turn off to use the region only for displaying metrics and voting on the content.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>010 (2)</td><td>Allow visitors to up vote</td>
+
<td>010,00</td><td>Allow visitors to up vote</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>001 (3)</td><td>Allow visitors to down vote</td>
+
<td>001,00</td><td>Allow visitors to down vote</td>
 +
</tr>
 +
<tr>
 +
<td></td><td>Display links:</td>
 +
</tr>
 +
<tr>
 +
<td>000,10</td><td>Display link to allow visitors to view reports</td>
 +
</tr>
 +
<tr>
 +
<td>000,01</td><td>Display link to allow visitors to view [[ContentMetrics]]</td>
 
</tr>
 
</tr>
 
</table>
 
</table>
  
* <code>'''%METRICS%'''</code> - A bit mask of what recorded metrics should be displayed. For clarity, these are group into seven visit and vote metrics and four date/time metrics:
+
* <code>'''%METRICS%'''</code> - A bit mask of what recorded metrics should be displayed. A comma is used to divide these into differnt sections.
  
 
<table class="wikitable">
 
<table class="wikitable">
Line 56: Line 87:
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>1000000 0000 (1)</td><td>Display total visits</td>
+
<td></td><td>Visitors:</td>
 +
</tr>
 +
<tr>
 +
<td>100,00000,0000</td><td>Display total visits</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0100000 0000 (2)</td><td>Display total unique visitors</td>
+
<td>010,00000,0000</td><td>Display total unique visitors</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0010000 0000 (3)</td><td>Display total vote value (up votes - down votes)</td>
+
<td>001,00000,0000</td><td>Display total visits for the current visitor</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0001000 0000 (4)</td><td>Display total up votes</td>
+
<td></td><td>Votes:</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0000100 0000 (5)</td><td>Display total down votes (as negative)</td>
+
<td>000,10000,0000</td><td>Display total vote value (up votes - down votes)</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0000010 0000 (6)</td><td>Display total visits for the current visitor</td>
+
<td>000,01000,0000</td><td>Display average vote value (only useful when allowing muti-value votes)</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0000001 0000 (7)</td><td>Display vote value for the current visitor</td>
+
<td>000,00100,0000</td><td>Display total up votes</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0000000 1000 (8)</td><td>Display date and time of the first visit</td>
+
<td>000,00010,0000</td><td>Display total down votes (as negative)</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0000000 0100 (9)</td><td>Display date and time of the most recent visit</td>
+
<td>000,00001,0000</td><td>Display vote value for the current visitor</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0000000 0010 (10)</td><td>Display date and time of the first visit for the current visitor</td>
+
<td></td><td>Dates:</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>0000000 0001 (11)</td><td>Display date and time of the most recent visit for the current visitor</td>
+
<td>000,00000,1000</td><td>Display date and time of the first visit</td>
 +
</tr>
 +
<tr>
 +
<td>000,00000,0100</td><td>Display date and time of the most recent visit</td>
 +
</tr>
 +
<tr>
 +
<td>000,00000,0010</td><td>Display date and time of the first visit for the current visitor</td>
 +
</tr>
 +
<tr>
 +
<td>000,00000,0001</td><td>Display date and time of the most recent visit for the current visitor</td>
 
</tr>
 
</tr>
 
</table>
 
</table>
 +
 +
Any character that is not a zero or a one will be deleted before being interpreted by the CM server. The comma will be used in these example for convention, but any other character could be used (e.g. +, :, or X) Similarly, if not all bit value are specified, those missing will default to zero (off).
  
 
== Examples ==
 
== Examples ==
Line 94: Line 139:
 
Here are some examples of region scripts. These assume that the containing web page resides on a '''%HOST-NAME%''' registered under ''etheradmin'' on the CM server ''www.scottdstrader.com'':
 
Here are some examples of region scripts. These assume that the containing web page resides on a '''%HOST-NAME%''' registered under ''etheradmin'' on the CM server ''www.scottdstrader.com'':
  
  http://www.scottdstrader.com/cm/region_create.php?id=etheradmin&region=article-id-1024&actions=011&metrics=11111001100
+
=== Exclude visit count and current visitor ===
 +
 
 +
  http://www.scottdstrader.com/cm/region_create.php?id=etheradmin&region=article-id-1024&actions=011&metrics=110,10110,1100
  
 
This tracks metrics for the region ''article-id-1024''. Names are unique identifiers on the host name and can be referenced across any number of pages or even multiple times within a page. For a blog, you may want to include a region script for an article in multiple places: the main page, the category page, and the article's permalink page.
 
This tracks metrics for the region ''article-id-1024''. Names are unique identifiers on the host name and can be referenced across any number of pages or even multiple times within a page. For a blog, you may want to include a region script for an article in multiple places: the main page, the category page, and the article's permalink page.
  
The actions ''011'' enable voting but do not record a unique visit when the page is displayed. This allows you to display metrics in a summary listing page without recording the viewing of those metrics as an actual visit. The actual page would contain the actions ''111'' in order to record the visit.
+
The actions ''011'' enable voting but do not record a unique visit when the page is displayed. This allows you to display metrics in a summary listing page without recording the viewing of those metrics as an actual visit. The actual page would contain the actions ''111'' in order to both record the visit and allow voting.
  
The metrics ''1111100'' (looking at the first seven) will display everything except those for the current visitor. The date/time metrics ''1100'' (the last four) will display the first and most recent visit, again excluding the first and most recent for the current visitor.
+
The metrics ''110,10110'' (looking at the first two groups) will display all visitor and vote metrics except the average vote and metrics for the current visitor. The date/time metrics ''1100'' (the last group) will display the date of the first and most recent visits but excluding those for the current visitor.
  
 
[[Category:ContentMetrics]]
 
[[Category:ContentMetrics]]

Latest revision as of 22:37, 7 May 2011

ContentMetrics is added to a web site by configuring a ContentMetrics (CM) server, registering the source web site that will communicate with the CM server, and configuring pages from the source web site to communicate to the CM server.

  • ContentMetrics (CM) server - a server that records visits and voting for any number of source web sites
  • Source web site - a web site that will send metrics to a single CM server

Configuring the ContentMetrics server

A ContentMetrics server (%CM-SERVER%) can be hosted on any web server that has MySQL 5+ and PHP 5+. Current available servers are:

The source web site must be registered with a user profile name (%PROFILE-NAME%) and host name (%HOST-NAME%). The %PROFILE-NAME% is an arbitrary and unique name that identifies the owner of one or more source web sites being tracked by ContentMetrics. The %HOST-NAME% is the actual hostname of the source web site with prefixes and suffixes (such as www. or .com) removed.

Configuring the source web site

The following style sheet and two JavaScript files must be added to the <head> section of any page that will communication with a CM server:

<link rel="stylesheet" type="text/css" media="screen"
    href="%CM-SERVER%/style/cm.css" />
<script type="text/javascript"
    src="%CM-SERVER%/javascript/prototype-1.6.0/prototype.js"></script>
<script type="text/javascript"
    src="%CM-SERVER%/javascript/cm.js"></script>

With these entries added, any number of regions can be added to the page. Each region will track metrics for that region alone and will display configurable results. The results will display wherever the script is placed on the page. Here is the basic format of the region script:

<script type="text/javascript"
    src="%CM-SERVER%/region_create.php?id=%PROFILE-NAME%&region=%REGION-ID%&votes=%VOTES%&actions=%ACTIONS%&metrics=%METRICS%">
</script>

Any number of individual regions can be added to a single page.

An example of a region script displaying the metrics 111,10111,1111

The following values are required:

  • %CM-SERVER% and %PROFILE-NAME% - The CM server that will track the data under the profile registered on that server
  • %REGION-ID% - A unique value within the registered %HOST-NAME%
  • %VOTES% - A comma-delimited pair of maximum up- and down-votes:
Value (position)Description
N,0(default: 1) Maximum positive vote value. If 1, then an up-arrow is displayed. If >1, then N number of right-pointing carets are displayed.
0,N(default: -1) Maximum negative vote value. If -1, then an down-arrow is displayed. If <-1, then N number of left-pointing carets are displayed.
  • %ACTIONS% - A bit mask of allowable actions for this view of the reigon:
Value (position)Description
User actions:
100,00Record each visit. Turn off to use the region only for displaying metrics and voting on the content.
010,00Allow visitors to up vote
001,00Allow visitors to down vote
Display links:
000,10Display link to allow visitors to view reports
000,01Display link to allow visitors to view ContentMetrics
  • %METRICS% - A bit mask of what recorded metrics should be displayed. A comma is used to divide these into differnt sections.
Value (position)Description
Visitors:
100,00000,0000Display total visits
010,00000,0000Display total unique visitors
001,00000,0000Display total visits for the current visitor
Votes:
000,10000,0000Display total vote value (up votes - down votes)
000,01000,0000Display average vote value (only useful when allowing muti-value votes)
000,00100,0000Display total up votes
000,00010,0000Display total down votes (as negative)
000,00001,0000Display vote value for the current visitor
Dates:
000,00000,1000Display date and time of the first visit
000,00000,0100Display date and time of the most recent visit
000,00000,0010Display date and time of the first visit for the current visitor
000,00000,0001Display date and time of the most recent visit for the current visitor

Any character that is not a zero or a one will be deleted before being interpreted by the CM server. The comma will be used in these example for convention, but any other character could be used (e.g. +, :, or X) Similarly, if not all bit value are specified, those missing will default to zero (off).

Examples

Here are some examples of region scripts. These assume that the containing web page resides on a %HOST-NAME% registered under etheradmin on the CM server www.scottdstrader.com:

Exclude visit count and current visitor

http://www.scottdstrader.com/cm/region_create.php?id=etheradmin&region=article-id-1024&actions=011&metrics=110,10110,1100

This tracks metrics for the region article-id-1024. Names are unique identifiers on the host name and can be referenced across any number of pages or even multiple times within a page. For a blog, you may want to include a region script for an article in multiple places: the main page, the category page, and the article's permalink page.

The actions 011 enable voting but do not record a unique visit when the page is displayed. This allows you to display metrics in a summary listing page without recording the viewing of those metrics as an actual visit. The actual page would contain the actions 111 in order to both record the visit and allow voting.

The metrics 110,10110 (looking at the first two groups) will display all visitor and vote metrics except the average vote and metrics for the current visitor. The date/time metrics 1100 (the last group) will display the date of the first and most recent visits but excluding those for the current visitor.