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]

Some reverse proxies (like Varnish) can inform MediaWiki whether mobile version is needed or not, thus creating a cache-friendly autodetection.

Detection using Varnish: mobile site on another domain[edit]

Suppose we use Varnish, and we want wiki.example.com to show desktop version, and m.wiki.example.com to show mobile version. Here is how to do that.

sub vcl_recv {
	remove req.http.x-wap; # Requester shouldn't be allowed to supply arbitrary X-WAP header
	if (req.http.host == "m.wiki.example.com") { # mobile domain
		set req.http.host = "wiki.example.com"; # desktop domain
		set req.http.x-wap = "no";
	}
}
sub vcl_hash {
	# Cache the mobile version of pages separately.
	#
	# NOTE: x-wap header should only have one value (if it exists),
	# therefore vcl_recv() should remove user-supplied X-WAP header.
	hash_data(req.http.x-wap);
}

LocalSettings.php should contain the following:

$wgMobileUrlTemplate = 'm.wiki.example.com'; // domain for mobile site

If you have many wikis, it may be convenient to use syntax like

$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.

Note: in this solution, built-in autodetection should be disabled ($wgMFAutodetectMobileView = false;), so that MediaWiki wouldn't question the decisions of Varnish.

Detection using Varnish: same domain for desktop/mobile site[edit]

Suppose we use Varnish, and we want wiki.example.com to show desktop/mobile version on the very same URLs (without creating additional domains like "m.wiki.example.com", etc.). Here is how to do that.

sub vcl_recv {
	remove req.http.x-wap; # Requester shouldn't be allowed to supply arbitrary X-WAP header
	if(req.http.User-Agent ~ "(?i)^(lg-|sie-|nec-|lge-|sgh-|pg-)|(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-|sendo|sharp|softbank|symbian|teleca|up.browser|webos)") {
		set req.http.x-wap = "no";
	}

	if(req.http.Cookie ~ "mf_useformat=") {
		# This means user clicked on Toggle link "Mobile view" in the footer.
		# Inform vcl_hash() that this should be cached as mobile page.
		set req.http.x-wap = "no";
	}
}
sub vcl_hash {
	# Cache the mobile version of pages separately.
	#
	# NOTE: x-wap header should only have one value (if it exists),
	# therefore vcl_recv() should remove user-supplied X-WAP header.
	hash_data(req.http.x-wap);
}

Note: in this solution, built-in autodetection should be enabled (it won't impact the cache):

$wgMFAutodetectMobileView = true;

Otherwise MobileFrontend misbehaves (if we don't set $wgMobileUrlTemplate, it ignores X-WAP header, if we do, it doesn't set "useformat" cookies for "toggle Mobile view' links in the footer").