Radioactivity 2: basics

Monday, December 5, 2011 - 12:04

With Radioactivity 2 nearly out of its beta form, I thought I'd write a bit about what it is and what you can do with it and most importantly walk you through on how to use it.

Radioactivity 2 allows you to track any fieldable entities; users, nodes, commerce products, etc. It can be used as a simple view counter but also as a popularity or activity meter, e.g. with it you can create a 'most viewed nodes at this moment' list. There is also limited rules which allows you to create an activity meter for basically whatever you want. 

For this tutorial we need to install and enable views, ctools and the radioactivity modules.

After that we need to create three things:

  1. Decay profile
  2. Radioactivity field
  3. View

Before we dwell deeper lets go through some of the terminology and settings.

Terminology

  • Energy: the hotness/popularity/views/etc. of the field.
  • Incident: an event where a value is added to or subtracted from energy.
  • Decay profile: defines whether or not the energy decays and has settings for it.
  • Granularity: how often is the field energy updated - in essence this defines the resolution in which the ordering happens. You can easily visualize this with the graph.
  • Half life: how long does it takes for energy to half. 
  • Cut off: at which point is the energy considered non-existent.
  • Incident storage: where are the incidents stored and how they are processed.

Settings

There are two very important parts on the Radioactivity settings page:

Salt for checksums and the Configuration (assist). To prevent 3rd parties from manipulating the field energies with scripts/bots, you should choose a good random string (a salt) used in calculating the checksums for the ajax callbacks. 

The second important part is to set up the radioactivity configuration file: radioactivity-boostrap.cfg.inc. This file holds all the required settings for the callback script to work without drupal and this is important for high traffic sites; If the file is missing the callback script does a partial drupal bootstrap so that it can function properly. Note that Live and Deferred storage types require drupal to bootstrap while the experimental File storage does not (non-boostrap memcache support is under development).

All that boils down to this: A user navigates to a node, node has a radioactivity field which - when visible - generates an incident with an ajax callback which increments the fields energy. The energy is manipulated with the settings defined in the decay profile (granularity, half-life) over time (cron runs) and it is considered to be zero when energy level is below the cut off level. 

Lets get started.

We will create a setup which tracks article popularity in a 6 hour timeframe so that the articles without views for 6 hours will have half of the initial energy and that it takes 50 views for them to reach the same energy level as a brand new one with 1000 energy.

1. Decay Profile

Navigate to the Radioactivity decay profiles page under Structure (admin/structure/radioactivity). Notice that there are no decay profiles yet, so lets create a decay profile by clicking the Add link at the top.

You are presented with the following form:

The form is filled with default values that should be suitable for most use cases with a good number of daily visitors. For this example we will use the defaults which is a 6 hour half life with 1 minute granularity. Note that finding the correct values for your site may take a few weeks and it usually requires some grooming.

At the moment there are three working storage types available:

  • Live storage - this updates the energy directly to the field, which means that all incidents affect the ordering in real time. Requires bootstrap.
  • Deferred storage - incidents are stored to a separate table and cron is responsible for adding the incidents to the field. Requires bootstrap.
  • File storage - this is an experimental lightweight incident storage which stores incidents to a temporary file. Non-bootstrap.
  • Memcached storage is going to be released soon.

Lets choose the live storage for this profile.

We're done here so save the profile.

2. Radioactivity Field

Next navigate to Content types under Structure (admin/structure/types) and click on manage fields on the Article content type we wish to add Radioactivity to. Create a new Radioactivity field. Once you have clicked save you are taken to the Field settings tab (which is empty). Click on the Edit tab. On this page select the profile we just created (since there is only one profile it is automatically selected) and add a reasonable default value for the energy field; 1000 points should be sufficient if one incident emits 10 points of energy.

Next, go back to the Content types page and click on the manage display link. Here we can configure the way the field works.

We can choose the amount of energy of one view emits or disable it by setting it to 0. We also have an option to display the amount of energy the field holds as a raw value or percentage. Usually this is only needed on admin listing pages, so lets decide not to show anything (Note: at the moment due to field caching these are not updated live; cache clear or a cron run solves the problem).

The final piece missing is a view which is ordered by the field we just created.

3. Views

Go to the Views listing page under Structure (admin/structure/views) and click on Add a new view. We will be listing Content of type Article with no default sorting on a page so choose some title and path for it also. The settings here do not really matter as we are only interested in the sorting order. Click on Continue and edit.

At the bottom left click on the add button to add a new sort criteria. On the following form we have to locate our field and add the field energy as the sorting criteria. Be sure to set the sorting to descending - otherwise you have the most popular articles at the bottom. Click on save and we're done!

After creating articles and viewing them - and of course running cron - the ordering on the listing page we just created should be that of the articles popularity in the wanted time frame defined in the decay profile.

--

That is the most basic use case for Radioactivity both for historical and technical reasons. 

Questions, thoughts?

Comments

I'm really excited about the different storage types. The memcache storage seems really interesting. That's an essential feature for supporting (near) realtime radioactivity on a site.

Thanks for this excellent contribution to the Drupal sphere :)

You're welcome :)

I aim to release the 2.0 before the end of this year and I should have the memcache storage ready by then. It won't be long!

Great stuff.

Avoiding the bootstrap, but still posting activity info to the Drupal DB so that it's useful on page build is certainly important on high traffic sites. Your filesystem save is one solution.

But how about another? Have you considered a way to use node.js, or _(fill-in-the-blank)_ and have the client JS talk to another server (presumably listening on a different port than 80), and have that server able to post directly into Drupal's DB (safely)? In this case, I wouldn't worry about having to have a second server type around; this case is only going to arise in high-traffic sites anyway, and those sites are typically going to have a fairly complex server setup with reasonable ops people who could handle another server.

(Of course, this gets easier in D8 if Larry Garfield's WSCCI initiative cuts Drupal bootstrap time to be negligible. But that's a ways off yet....)

2.0 comes with support for memcached storage, so that takes the overhead even lower :) I've thought about using node.js as a transport and I'm pretty sure one could quite easily write a storage type for it - I just haven't gotten around to try it. It would also allow the system to do a lot more than just register entity views so it would be pretty cool to try out.

A while back I started a little sandbox project which would provide a reusable way of sending 'incidents' to Drupal (http://drupal.org/sandbox/tcmug/1364084 - no commits yet though) - once finished - it should provide a dead simple way to send incidents to a pluggable storages with a pluggable transports and pass them on to Drupal for handling. Time will tell where it ends up and IF it ends up being useful.

this is a very handy tool. Our use case is to display "most active" products on our webstore (Relatively short radioactivity cut down time to ensure that most viewed products are updated regularly, but not too often)

Hey, great tutorial.

It is probably the only tutorial online on how create "top views" with radioactivity.

But, i have a question if you can explain me. You're talking about top items who has been viewed, but what about items who has been buyed?

I'm looking for "top sellers" on my site but i can't achieve it, i don't see the "Commerce Product Popularity rule" into the store configuration settings..

Have you an idea on the subject?

Thanks,

I wish to implement this module in marketinghypnotism . com. Do you have a list of websites that implement this module? I wish to see the behaviour as a web visitor.

This was so easy to follow and clearly set out step by step. Thanks for the clarity - it just works ;-)