Extension:MobileFrontend/Configuring browser auto-detection

This document explains how a site admin can enable a mobile site for their mediawiki extension such that when a user visits the site from a mobile device they are automatically redirected to the mobile view rather than the desktop view.

Built-in autodetection

As of commit 5a1867e, MobileFrontend supports automatic device detection with minimal configuration. All you need to do is set:

$wgMFAutodetectMobileView = true;

in your LocalSettings.php. While this is the easiest method, it will almost certainly be the least performant. This solution is NOT compatible with front-end caching, as it provides no way for your cache to know the difference between a mobile view and a desktop view.

Apache Mobile Filter (AMF)

As of commit 0fb2c72d, MobileFrontend supports the Apache Mobile Filter (AMF) for device detection. You must be using the Apache webserver. Follow instructions for setup/configuration of AMF, and it should 'just work'. This functions very similarly to built-in auto detection, and will not be compatible with front-end caching without special configuration.

Webserver/proxy-cache device detection

MobileFrontend supports the usage of two separate domains for a mobile version and desktop version of the site, and this is the recommended approach. While more complicated to set up, it is ultimately easier to manage and to scale - particularly if you are using frontend caching. This way, you need to point both domains, mobile and desktop, to the same MediaWiki installation, however set a custom header for requests coming from the mobile domain.

For example, in Varnish:

sub vcl_recv {
   if (req.http.host == "<mobile domain>") {
       set req.http.host = "<desktop domain>";
       set req.http.X-WAP = "no";
   }
}

Then, you will need to define your mobile domain by setting $wgMobileUrlTemplate in LocalSettings.php.

The simplest, and likely most common, thing to do is to define a completely unique domain for your mobile site:

$wgMobileUrlTemplate = 'mobile.mydomain.com';

Or, if you use one configuration to manage multiple wikis, you could define a mobile domain template:

$wgMobileUrlTemplate = '%h0.m.%h1.%h2';

Where '%h<#>' maps to a segment of the hostname of $wgServer. So, if $wgServer = 'en.wikipedia.org';, %h0 is 'en', %h1 is 'wikipedia', %h2 is 'org'. Given this, the above $wgMobileUrlTemplate will automatically interpolate your mobile URL as 'en.m.wikipedia.org'. This is particularly useful for the WMF and projects like Wikipedia, which follow a template of <lang code>.wikipedia.org, so the mobile domain will always look like <lang code>.m.wikipedia.org.

If you don't want to use subdomains for the mobile version of a wiki, you can also use the following snippet that adds ?useformat=mobile based on user preferences and the user agent (note this assumes you have /w/index.php as $wgScriptPath and /wiki/ as $wgArticlePath):

sub identify_device {
        # Used in vcl_backend_fetch and vcl_hash
        set req.http.X-Device = "desktop";

        # If the User-Agent matches the regex (this is the official regex used in MobileFrontend and WMF production), 
        # and the cookie does NOT explicitly state the user does not want the mobile version, we
        # set X-Device to phone-tablet. This will make vcl_backend_fetch add ?useformat=mobile to the URL sent to the backend.
        if (req.http.User-Agent ~ "(?i)(mobi|240x240|240x320|320x320|alcatel|android|audiovox|bada|benq|blackberry|cdm-|compal-|docomo|ericsson|hiptop|htc[-_]|huawei|ipod|kddi-|kindle|meego|midp|mitsu|mmp\/|mot-|motor|ngm_|nintendo|opera.m|palm|panasonic|philips|phone|playstation|portalmmm|sagem-|samsung|sanyo|sec-|semc-browser|sendo|sharp|silk|softbank|symbian|teleca|up.browser|vodafone|webos)" && req.http.Cookie !~ "(stopMobileRedirect=true|mf_useformat=desktop)") {
                set req.http.X-Device = "phone-tablet";
        }
}

sub vcl_recv {
        # It is recommended to put this at the very top in vcl_recv
        call identify_device;
}

sub vcl_hash {
        # FIXME: can this be ^/wiki/ only?
        if (req.url ~ "^/wiki/" || req.url ~ "^/w/load.php") {
                hash_data(req.http.X-Device);
        }
}


sub vcl_backend_fetch {
        if ((bereq.url ~ "^/wiki/" || bereq.url ~ "^/w/index.php\?title=") && bereq.http.X-Device == "phone-tablet") {
                if (bereq.url ~ "\?") {
                        set bereq.url = bereq.url + "&useformat=mobile";
                } else {
                        set bereq.url = bereq.url + "?useformat=mobile";
                }
        }
}