Tracker

The Tracker plugin creates fancy analytic reports of activity of your mass mailings. You can think of a mass mailing being a "campaign" if you'd like.

The activities that are logged and reported include:

# subscribers when a mass mailing was sent out
# of recorded clickthroughs
# of recorded opens/views
# bounces, both soft and hard

Birds-Eye View

These fancy reports include the above information in tabular data, as well as in a line graph, for past mass mailings to help you spot general trends. This information can also be exported into .csv files, giving you more flexibility, specific to your needs.

Individual Messages/Campaigns

Along with the birds-eye view of seeing data of many messages at once, each mass mailing/campaign can also be explored.

Clickthroughs are broken down per # of clicks per link
Clickthroughs are also broken down by country of origin, displayed in both a table and map.
Message opens are also broken down by country of origin and displayed both in a table and map.
Bounces, both soft and hard bounces are listed by date and email address of the bouncee.
Clicking on the email address will allow you to view the data about the bounced message itself in the bounce handler plugin.

(No bounces will be recorded, unless you've separately set up and installed the Bounce Handler plugin that comes with Dada Mail)

If you suddenly get a ton of bounced messages for a mailing from addresses you know look legitimate, there's a good chance that something seriously went wrong in the delivery part of a mass mailing. The reports that the Tracker plugin links to may help in resolving this problem.

All this message-specific data can also be exported via .csv files that may be downloaded.

Installing tracker.cgi

This plugin can be installed during a Dada Mail install/upgrade, using the included installer that comes with Dada Mail. The below installation instructions go through how to install the plugin manually.

The tracker.cgi plugin comes with Dada Mail. You'll find it in the, dada/plugins directory with the file name, tracker.cgi

Change its permission to, 755.

List Control Panel Menu

Now, edit your .dada_config file, so that it shows the Tracker in the left-hand menu, under the, Plugins heading:

First, see if the following lines are present in your .dada_config file:

 # start cut for list control panel menu
 =cut

 =cut
 # end cut for list control panel menu

If they are, remove them.

Then, find these lines:

 #                                      {
 #                                      -Title      => 'Tracker',
 #                                      -Title_URL  => $PLUGIN_URL."/tracker.cgi",
 #                                      -Function   => 'tracker',
 #                                      -Activated  => 1,
 #                                      },

Uncomment the lines, by taking off the, "#"'s:

                                        {
                                        -Title      => 'Tracker',
                                        -Title_URL  => $PLUGIN_URL."/tracker.cgi",
                                        -Function   => 'tracker',
                                        -Activated  => 1,
                                        },

Save your .dada_config file.

Using tracker.cgi

For the most part, the Tracker plugin simply reports data that's collected about your mass mailings.

Preferences

You may enabled/disable any of the items Tracker track independently in the plugin's Preferences.

Track Message Clickthroughs

When enabled, allows you to use the Redirect Tags to track links that are clicked on in your mass mailing message.

Auto Tag Message Links

When selected, ALL links found in an email message will be tracked by converting them into redirect tags and then clickthrough-tracked links.

Manually Tag Message Links

When selected no link will be clickthrough-tracked by default, but you may craft your own Redirect Tags manually, for any link you'd like to track.

Track Message Opens

When enabled, allows you to track open/viewing of messages.

Opens are tracked, by counting the requests of a small, special image that's embedded in your email message. This means, you'll need to send your mass mailings in HTML, or have Dada Mail convert your PlainText messages to HTML. This can be done in the list control panel, under: Mass Mailing - Options; enabled the option labeled, Convert PlainText-only Mass Email Messages to HTML

Mail readers sometimes block the display of images in your HTML email messages. Because of this, Dada Mail will also count the first clickthrough of a tracked link as also an, "Open". This does work for both PlainText and HTML messages

Track "Forward to a Friend"

When enabled, use of the "Forward to a Friend" function for each message will be counted.

More Information: http://dadamailproject.com/d/features_forward_to_a_friend.pod.html

Track Archive Views

When enabled, allows you to track every time a visitor views an archived message.

Track Bounces

When enabled, any bounces, both soft or hard, are tallied up. You will need to have the bounce handler installed for this to work.

Clean Up Tracker Reports

When enabled, tries to get rid of a lot of the, "line noise" that could be present in your logs, because of weird logging behaviour.

This will also remove opens/clickthroughs and even bounces from test messages, so if you are sending a test message and you want to test out if the clickthrough URLs are working, etc, disable this preference, send your test messages and enable it, after you're done.

Clickthroughs

Clickthroughs are tracked by creating a "Redirect" tag, that holds the URL you want to track.

If you have a PlainText message you want to send and you want to track who clicks on a specific link, say,

 http://example.com

You would write this URL inside a redirect tag, like this:

<?dada redirect url="http://example.com" ?>

Replace "http://example.com" with whatever URL you would like to track.

This redirect tag will be replaced by Dada Mail with a URL that, when clicked, will record the click and redirect your user to the URL you specified within the tag.

In an HTML message, you would craft the redirect tag the same way, except that the redirect tag goes within the, "href" paramater of the, "a" tag. Again, this sounds difficult, but for example:

If you have a link created like this:

        <a href="http://example.com">
         Go to my Example site!
        </a>

You would simply, like before replace,

 http://example.com

 with the redirect tag,

<?dada redirect url="http://example.com" ?>

and put this inside the href parameter, like this:

<a href="<?dada redirect url="http://example.com" ?>"> Go to my Example site! </a>

If you have messages where you want to track many, many links and the above sounds tedious and easy to mess up, or your authoring workflow doesn't play nice with these redirect tags, there is an option in the preferences labeled,

Auto Tag Message Links

Which will do all this for you, automatically. Any links that you have manually added a redirect tag to will be untouched, just in case.

Backwards Compatibility with the [redirect=] tag

Past versions of Dada Mail (before v4.5.0) used a different syntax for redirect URLs. The syntax looked like this:

 [redirect=http://example.com]

This tag format is still supported, but consider it deprecated.

Clickthrough Tags and WYSIWYG editors (CKeditor/Tiny MCE/FCKeditor)

In-browser HTML WYSIWYG editors have a hard time working with Dada Mail's redirect tags, and will corrupt the tags by turning many of the characters into their entities, like this:

        <a href="&lt;?dada redirect url=&quot;http://example.com&quot; ?&gt;">
         Go to my Example site!
        </a>

If you use a WYSIWYG editor with Dada Mail, we suggest using the, Auto Tag Message Links option in Dada Mail, or disable the WYSIWYG Editor.

Copying and pasting HTML from a separate program which does not corrupt the tag (like Dreamweaver), will still be affected even if you simply paste the HTML into the WYSIWYG editor and even if you do it into the HTML Source.

For most other Desktop-based WYSIWYG editors, including Dreamweaver, double-check that the editor does not corrupt the redirect tag.

Limitations of Redirect tags

One thing that you cannot do with the redirect tags, is embedd other Dada Mail Template Tags within the redirect tag.

This will not work:

 <?dada redirect url="http://example.com/index.html?email=<;!-- tmpl_var subscriber.email -->" ?>

Capturing Additional Paramaters with Redirect Tags

It is possible to capture and log additional paramaters in the redirect tags, besides the URL clicked on. For example, you can craft a redirect tag, like this:

 <?dada redirect url="http://example.com"; custom_param="some value" ?>

Where, custom_param is the additional paramater you'd like to capture and, some value is the value you'd like to save. The value can be different for different links, in different messages, across different messages, etc.

Treat this feature as experimental. The Tracker plugin will not display additional paramater data, but the data can be found in the downloadable .csv files created by the Tracker Plugin.

Before using your additional paramaters, make sure both the dada_clickthrough_urls and dada_clickthrough_url_log tables both hold a column named the same as this paramater as the last column.

In our above example, the following SQL will do the job:

        ALTER TABLE dada_clickthrough_urls    ADD custom_param TEXT;
        ALTER TABLE dada_clickthrough_url_log ADD custom_param TEXT;

You may add as many different params as you would like.

Opens

Opens tracking allows you to keep count of how many times a message is viewed by your subscribers.

Subscriber Count Tracking

Subscriber Count Logging simply records how many subscribers are on your mailing list, at the time a mass mailing goes out.

Subscriber Count Logging does not work by tallying up all individual subscribers/unsubscribes, so the graph created will tend to look fairly normalized.

Specific Plugin Config Variables

These variables have defaults saved in this plugin itself, but encourage you to reset the defaults to the values you may want, instead in your .dada_config file, in the, $PLUGIN_CONFIGS variable, under the, Tracker entry

Plugin_Name

The name of this plugin

Plugin_URL

The URL of this plugin. This is usually found by default, but sometimes the default doesn't work correctly. If this happens to you, fill it out in this variable

GeoIP_Db

This variable holds the file path to the location ofthe GeoIP database. The GeoIP database is a IP Address -> Location lookup table, to quickly and easily figure out the location based on the IP Address.

This database is updated monthly and new copies can be obtained at:

http://geolite.maxmind.com/download/geoip/database/GeoLiteCountry/GeoIP.dat.gz

The database is licensed under the LGPL, so it's OK to ship Dada Mail with a copy of this database.

If you find it necessary, you may keep a copy of this database outside of Dada Mail and update it regularly and tell this plugin where to find the database to use.

For more information, see:

http://search.cpan.org/~borisz/Geo-IP-PurePerl-1.25/lib/Geo/IP/PurePerl.pm

This product includes GeoLite data created by MaxMind, available from http://www.maxmind.com/

GeoLiteCity_Db

Like, GeoIP_Db, this variables holds the absolute file path to the City Geo IP database. Copies are obtained from,

http://www.maxmind.com/download/geoip/database/GeoLiteCity.dat.xz

Getting the Most Out of the Tracker Plugin

Turn On Archiving

Having messages archived allows you to see the message the reports are generated for. Without it, you'll just have a long list of dates/numbers to remember about your mass mailings/campaigns.

You can have archiving enabled, but not show your archives publically. This is a better option than disabling archiving completely.

Install the Bounce Handler

The bounces that are logged and shown with the Tracker plugin only work if you have the bounce handler installed, It's installation is a little more trickier than the Tracker plugin, but it's well worth it for data it generates

Auto Tag Message Links

It's interesting to track one or a view links using the redirect tags to track clickthroughs, but another trend to follow would be how all links in an email message fare against each other.

Discussion Lists and Clickthrough Tracking

Discussion Lists may not benefit as much from clickthrough tracking and tracking all lists in a message, since the list owner gives up control over the content of a message. Rather, the members of a list create the content and having clickthrough URLs in place of the actual URLs written can get in the way of discussions. There's also a chance that nefarious URLs can be hidden within a clickthrough URL - not something you want.

Sending a Test Message?

Test message will not be shown in the Tracker's reports.

Compatibility with clickthrough_tracking.cgi

The previous iteration of this plugin (tracker.cgi) was called, clickthrough_tracker.cgi. Do not use this old plugin with anything newer than v4.5.0 of Dada Mail. It will not work correctly.

Upgrade Notes

The below is information for people who have used the clickthrough_tracking.cgi script in past versions of Dada Mail (before v4.5.0) and want to take advantage of the new Tracker plugin and also want to move over the old logged data.

Importing Old Clickthrough Logs

Data saved within the older, PlainText clickthrough logs would have to be moved over,

There is a script called, dada_clickthrough_plaintext_to_sql.pl located in the, dada/extras/scripts directory that will do this conversion. Move it into your, dada directory, change its permissions to, 755 and run it once in your web browser. It may take a few minutes to run to completion.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.