Extension:MobileFrontend/Configuring browser auto-detection

From MediaWiki.org
Jump to: navigation, search

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[edit]

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)[edit]

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[edit]

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 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";
                }
        }
}