API: Script: Redirect

Redirect Script Basics

The UCLA Mobile Web Framework provides a script that redirects "mobile" users away from one page to another. The basic syntax for enabling such a redirect is as follows, where {MOBILE_PATH} is a URL-encoded absolute path for mobile users:

<script type="application/javascript" 
    src="http://{MOBILE_DOMAIN}/assets/redirect/js.php?m={MOBILE_PATH}">
</script>

At the most basic level, the advantage to using this script, as opposed to a self-engineered one, is that it considers user agents consistently with the mobile web framework itself without requiring assets/js.php. This script delivers the absolute least amount of Javascript necessary to invoke a redirect (one line), or none at all if the user should not be redirected. The redirect script also includes other benefits such as override capabilities and domain specificity (see below).

Overriding the Redirect

Sometimes a user on a mobile device may desire to view the full site, rather than the mobile site.

The redirect script makes this kind of functionality possible through a very simple mechanism: simply set the GET parameter ovrrdr=1 on the requested page (the script page considers this its referrer). For example: given the page sample.php that includes the script file assets/redirect/js.php?m={MOBILE_PATH}, if one requests sample.php?ovrrdr=1, then the user will not be redirected to {MOBILE_PATH}.

The redirect script maintains the preference specified by the ovrrdr parameter for all pages that include the script. By default, it maintains the preference for five minutes, refreshing the preference whenever the user lands on any page that also includes the redirect script.

There are two reasons an override on the redirect may stop:

• Five minutes pass without the user visiting a page that includes assets/redirect/js.php.
• The user visits a page that uses the mobile framework, most notably the assets/js.php file.

To avoid conflict between these scripts, assets/redirect/js.php file should never be included on the same page as the framework assets/js.php file.

Domain Specificity and Expiries

In some cases, it may not make sense to override the redirect universally. For example, one application might have links to another and the user might want to be on the desktop site for the first application, but on the mobile site for the other application. Therefore, the script has a redirect preference for an individual "domain", where the domain is specified in the include script path:

<script type="application/javascript" 
    src="http://{MOBILE_DOMAIN}/assets/redirect/js.php?m={MOBILE_PATH}&d={DOMAIN}">
</script>

In this case, the override call is still the same: request sample.php?ovrrdr=1 to prevent the redirect on sample.php. In this case, however, the setting will only apply to pages that include js.php with the GET parameter d equal to {DOMAIN}.

For a specific domain, one may also set the expiration time on the preference to something besides five minutes via the GET parameter e. This parameter is interpreted as the number of seconds until expiration from the current time:

<script type="application/javascript" 
    src="http://{MOBILE_DOMAIN}/assets/redirect/js.php?m={MOBILE_PATH}&d={DOMAIN}&e={EXPIRY_SECONDS}">
</script>

This script thus provides a very powerful cross-domain way of achieving redirection and maintaining user browser preferences.

User Prompting

Another option when using the redirect script is to let the user choose whether or not they want to view the mobile or desktop version of a site. This can be done with the prompt GET parameter. If the prompt parameter is specified in the redirect script URL, when a user arrives at the page on a mobile device, they will be presented with an overlay asking whether they want to view the "Mobile Site" or the "Full Site". The default prompt message is "Select a browsing mode:", which can also be defined to be a custom message by giving the prompt GET parameter a value. Like the mobile redirection path, this value should be a URL encoded string with the desired message:

<script type="application/javascript"
    src="http://{MOBILE_DOMAIN}/assets/redirect/js.php?m={MOBILE_PATH}&prompt={PROMPT_MESSAGE}">
</script>