Mobile browser detection and redirection in eZ Publish

When you are setting up a mobile website separate from the main website, one of the elements that tends to be an after-thought is main-to-mobile site redirection. This article goes through some of the considerations regarding creating a mobile setting, and main-to-mobile site redirection specifically.  It explains how to use Apache Mobile Filter as one option to facilitate mobile device detection and redirection.

General mobile site considerations

This article assumes that you already have a traditional main website and have decided to build a mobile site to be directly accessed or to be accessed through a hybrid mobile application. The process of "going mobile" starts a few steps back, by figuring out your mobile goals, use cases, content, and implementation strategy (including deciding whether to build a mobile application, just a mobile website, or both).

Another consideration would be the choice of URL for the mobile site: we suggest using m.yoursite.com, as that is standard best practice and allows for easier cookie sharing with the main yoursite.com domain.

Depending on your content management system, building out the structure and templates for the mobile site can take as little as a couple of hours for a basic setup. With eZ Publish, this is well-documented. The basic steps include create a new siteaccess with a new subdomain and a design with some basic templates, CSS, JavaScript, and mobile-centric image sizes. In eZ Publish, creating a mobile siteaccess enables you to have access to the same content base as the main site.

Of course, there are many more considerations here depending on the complexity of your site -- for example, you might need to enable certain site features based on the capabilities and screen resolution and size of each mobile visitor's device. A concrete capability example is the web storage API in HTML5.

Redirection behavior and implementation

When you get to the issue of the redirection user experience, you want to define what should happen when you detect that a visitor is using a mobile browser. Our suggestion is as follows: for full-size browsers, we will implement no special redirection; the main site is always available at the main URL, and the mobile site is always available at the full URL.  For mobile browsers, we will automatically redirect users to the mobile site on their first visit to the main site.  On the mobile site will be a link back to the main site.  If a mobile user clicks on the link to view the main site, their choice will be remembered, so that from that point on, they will not get any auto-redirection from the main site to the mobile site; they'd have to specifically request the mobile site URL to access the mobile site.  An optional extra step would be to provide a link from the main site back to the mobile site for mobile users, which would store their choice and once again enable the automatic main-to-mobile redirection.

When it comes to the actual implementation of the device detection and redirection logic, the typical approach is to look at the HTTP request headers "User-Agent" and possibly "UAProf". These request headers are matched against a list of strings representing the many different mobile devices. You must consider at which level in your website to put the logic:

• At the content delivery network (CDN) or reverse proxy (such as Varnish) level, if applicable
• At the web server (such as Apache) level
• At the application level

For performance reasons, you typically want to choose the highest level (in order of how close it is to the end user; and in descending order of how close it is to your application) that is applicable.

Some CDNs such as Akamai can handle this for you in a black box scenario. Within the configuration for a reverse proxy such as Varnish, you can implement your own comparisons against many of the publicly available lists such as WURFL and DetectRight (be sure to cache the list and periodically update it!); or, you can have the web server or application perform the detection and store the result as a user cookie.

The web server level is where you can implement a solution as simple as Apache rewrite rules. We'll discuss this after mentioning the application level, since the Apache Mobile Filter solution is implemented at the web server level and discussed in more detail shortly.

At the application level, you can add some mobile detection code specific to your application coding language or use the framework provided by your application, if such a framework exists. For example, in eZ Publish there is a built-in solution available in its trunk code repository, which should be included in the eZ Publish Enterprise 4.7 release in May 2012, and in the eZ Publish Community 2012.01 release due out very shortly.

Apache Mobile Filter

Apache Mobile Filter (AMF) is a set of Perl modules, most notably its mobile detection modules, implemented at the web server level, in front of your application. This makes it independent of your coding language and/or content management system. It also addresses another problem typical with application-side solutions, which is the need to maintain rule sets regarding mobile device user agents. (We must note that this is not a problem with the idea of an application-side implementation, but is simply common with some specific implementations.) Apache Mobile Filter can easily be set up to periodically sync with common mobile device user agent lists such as WURFL and DetectRight.

In addition to performing mobile device detection, Apache Mobile Filter (AMF) has a few additional tools such as redirection and image resizing, which you can read about further on its website.

Once you've installed AMF and its pre-requisites (see the appendix at the end of this article for some notes on installing it on CentOS), each page request will have some additional environment variables that you can use in your virtual host configuration. Most interesting for a basic setup are the "AMF_DEVICE_IS_MOBILE" and "AMF_DEVICE_IS_TABLET" variables.

Two sets of virtual host rewrite rules can accomplish the redirection behavior we described earlier. Let's look at them in a somewhat reversed order.

The first rule set handles the scenario where a mobile visitor clicks a link to return to the main site. The link should contain a GET variable "fullbrowser", which will store a cookie to signal to the redirection logic (in the second rule set) to disable the auto-redirection for mobile devices.

# Back to the full site, set a cookie
RewriteCond %{HTTP_HOST} =www.yoursite.com [NC]
RewriteCond %{QUERY_STRING} ^fullbrowser$ [NC]
#CO=name:value:domain:lifetime:path
#Set the cookie for a year
RewriteRule .* - [CO=fullbrowser:1:.yoursite.com:525600]

The second rule set acts on the environment variables set by AMF to redirect to the mobile site if neither the "fullbrowser" cookie nor the "fullbrowser" GET variable are set. Notice that we're also exempting tablet devices from this redirect logic, as we want our example site's full experience to be the default for tablets:

# Mobile switching dependent on Apache Mobile Filter
RewriteCond %{HTTP_HOST} =www.yoursite.com [NC]
RewriteCond %{HTTP_COOKIE} !fullbrowser=1 [NC]
RewriteCond %{QUERY_STRING} !fullbrowser [NC]
RewriteCond %{ENV:AMF_DEVICE_IS_MOBILE} =true [NC]
RewriteCond %{ENV:AMF_DEVICE_IS_TABLET} =false [NC]
RewriteRule ^(.*)$ http://m.yoursite.com$1 [R=302,L]

Appendix: quick guide to installing Apache Mobile Filter on CentOS 5.x

Note: official installation documentation is available here

1. Update Perl; you need at least 5.8.9, and CentOS ships with 5.8.8.  Be sure to download an even numbered version such as 5.14.x; odd-numbered versions are development versions.

wget http://search.cpan.org/CPAN/authors/id/F/FL/FLORA/perl-5.14.2.tar.gz
tar -zxf perl-5.14.2.tar.gz
cd perl-5.14.2
# fPIC flags are important to compile mod_perl later
sh Configure -de -Dusethreads -Accflags='-fPIC'
make
make test
make install

2. Your compiled perl binary should be at /usr/local/bin/perl. Remove or back up your default /usr/bin/perl then create a symbolic link:

ln -s /usr/local/bin/perl /usr/bin/perl

3. Install mod_perl

wget http://perl.apache.org/dist/mod_perl-2.0-current.tar.gz
tar -zxf mod_perl-2.0-current.tar.gz
cd mod_perl-2.0.5
perl Makefile.PL
make
make test
make install

4. Add mod_perl to your Apache configuration file httpd.conf:

LoadModule perl_module modules/mod_perl.so

5. Install development tools, specifically for apxs for an easier AMF install process:

yum install httpd-devel

6. Install memcached

yum install memcached

7. Install Apache Mobile Filter:

cpan Apache2::AMFWURFLFilter Apache2::Filter Apache2::RequestRec Apache2::RequestUtil Apache2::Connection\
Apache2::SubRequest Apache2::Log CGI::Cookie\
APR::Table CGI::Cookie LWP::Simple Imager Image::Resize Image::Scale IO::Uncompress::Unzip Cache::FileBackend Cache::Memcached
wget http://www.sourceforge.net/projects/mobilefilter/files/latest/download
tar -zxf Apache2-ApacheMobileFilter-3.50.tar.gz
cd Apache2-ApacheMobileFilter-3.50
perl Makefile.PL
make
# No tests available
make install

8. Create a directory for data caching (/home/amfdata)

9. Configure httpd.conf (see the AMF configuration tool for more information; this example uses the most basic detection filter)

# For caching purposes
PerlSetEnv AMFMobileHome /home/amfdata
PerlSetEnv AMFProductionMode true
PerlTransHandler +Apache2::AMFLiteDetectionFilter
# This is technically supposed to be only if you are using automatic switching, but in the Perl script the switch to download the tablet definition depends on this setting
PerlSetEnv ForceTabletAsFullBrowser true
# These are some parameters if you want to use the automatic switcher
#PerlSetEnv WildCardRedirect true
#PerlSetEnv ForceTabletAsFullBrowser true
#PerlSetEnv FullBrowserMobileAccessKey fullbrowser
#PerlSetEnv FullBrowserUrl http://www.yoursite.com
#PerlSetEnv MobileVersionUrl http://m.yoursite.com
#PerlTransHandler +Apache2::AMFSwitcher
# log all requests for debugging purposes
#PerlTransHandler +Apache2::AMFTrace

10. Logic in your virtual host file to perform redirection outside of AMF:

# Mobile switching dependent on Apache Mobile Filter
RewriteCond %{HTTP_HOST} =www.yoursite.com [NC]
RewriteCond %{HTTP_COOKIE} !fullbrowser=1 [NC]
RewriteCond %{QUERY_STRING} !fullbrowser [NC]
RewriteCond %{ENV:AMF_DEVICE_IS_MOBILE} =true [NC]
RewriteCond %{ENV:AMF_DEVICE_IS_TABLET} =false [NC]
RewriteRule ^(.*)$ http://m.yoursite.com$1 [R=302,L]

# Back to the full site, set a cookie
RewriteCond %{HTTP_HOST} =www.yoursite.com [NC]
RewriteCond %{QUERY_STRING} ^fullbrowser$ [NC]
#CO=name:value:domain:lifetime:path
#Set the cookie for a year
RewriteRule .* - [CO=fullbrowser:1:.yoursite.com:525600]

You can test these rules on your mobile device or on a desktop browser using a tool that modifies your user agent information, such as the User Agent Switcher extension for Firefox.