Mobile Detection and Redirect

Mobile Detection and Redirect (MD&R) identifies requests originating from mobile devices and redirects those requests to your mobile-optimized site. MD&R leverages ​Akamai​’s device characteristics library, a frequently updated data system that provides information about the requesting device. This lets you provide customized content based on any of several device characteristics.

How it works

You create match criteria to identify the classes of devices you want to direct to each of your device-specific sites. You assign a redirect location to each device class. Then, MD&R redirects requests to the appropriate site:

  • It reads a device identifier (the user-agent string) from the requesting device.

  • It looks up the relevant values in the device characteristics library.

  • It compares those values to the match criteria in any MD&R rules you created.

If the request passes the match criteria conditions, it redirects the request to the location you specified in the rule.

Which MD&R template is right for your site?

Template NamePurpose
Mobile Detection & RedirectThe most basic redirect rule template: Redirect requests from mobile devices to your mobile site.
Mobile Detection & Redirect (with desktop cookie logic)For sites that use desktop cookies and/or desktop query string parameters.
Mobile Detection & Redirect (with Usablenet logic)A template pre-configured to be compatible with Usablenet.

For detailed explanations of how the templates work, see MD&R: Summary of template logic.

Preserving end-users’ site preferences: Cookies and query string parameters

You might have included an option on your website for end-users to change which site they use: for example, a "Go to Desktop Site" link on your mobile site. Usually, you will want to preserve this information so that a user who has requested the desktop site isn't redirected to the mobile-optimized site every time they request a page. One way to do this is to use desktop cookies or desktop query string parameters with your site preference links.

If your site uses cookies or query string parameters in this way, you will probably want to use the desktop cookie logic template. Also, a different template is available to accommodate sites where user site preference is managed with Usablenet, a third-party mobile site hosting service.

MD&R: Applying and modifying templates

Add an MD&R template to your rule

  1. In ​Control Center​, go to the Property Manager homepage.
  2. Under Manage Versions and Activations, go to the Version History tab and select a version link.
  3. In the Rules list, click the Add button.
  4. In the list of categories on the left, click Redirect.
  5. Select a template, and click the Insert Rule button.
  6. Customize the default values to meet your needs. See Customize your template.

Customize your template

  1. In the rule at the top of the list, add one or more criteria that describe the devices you want to redirect. Begin by selecting Device Characteristics from the first drop-down menu.
  2. Optionally, add match criteria that filter on other elements of the request.
  3. Specify a redirect destination URL in the Redirect behavior (see MD&R: Configuring a Redirect behavior).
  4. If using a desktop query string parameter, enter its name and value in every instance of those fields in the match criteria and behaviors.
  5. If using a desktop cookie, enter its name, value, and expiration in every instance of those fields in the match criteria and behaviors.

Order of operations

List rules from the least specific at the top to the most specific at the bottom. To change the listed order, click and drag the rule names in the Rules list on the left. Likewise, behaviors within a rule are executed from top to bottom. To change their order, click and drag a behavior’s pane.

If a parent rule’s match criteria aren't met, its child rules do not apply; the logic advances to the next rule at the same level as the parent rule.

MD&R: Configuring a Redirect behavior

The Redirect behavior sends incoming requests matching your criteria to the location you indicate. The location can be fixed (a static redirect) or can preserve elements of the requested URL.

ScenarioThese Settings......change requests like this:
Directory paths on the mobile site are located in the /m/ directory and are exactly parallel to the non-mobile site.
  • Hostname: Same as request

  • Path: Prefix requested path

  • Path Prefix: /m



Mobile site is a subdomain of the non-mobile site. Directory paths are not similar, so all mobile redirects are sent to the mobile site's home page.
  • Hostname: Substitute requested subdomain

  • Substitute Subdomain: m

  • Path: Static path

  • Static Path: /home



Mobile site is a subdomain of the non-mobile site. Directory paths are exactly parallel to the non-mobile site.
  • Hostname: Substitute requested subdomain

  • Substitute Subdomain: m

  • Path: Same as request



MD&R: Preventing URL-Based downstream caching

In some cases, requested content can be cached beyond the edge server using the URL of the original request. This can interfere with device-based caching settings.

To address this, the MD&R templates include the Modify Outgoing Response Header behavior, which ensures that your configured device characteristics match criteria override the user's local caching behavior.

In MD&R, the only valid settings for this behavior are to add a header named Vary with the value User-Agent.

MD&R: Summary of template logic

The following summaries describe the logic of the match criteria and behaviors in the order and nesting levels they appear in each template. This information is also available in the Property Manager interface. Click a rule's name in the Rules list to display a narrative description of the logic for that step in the comment box at the top.

Mobile Detection & Redirect

Identify the requesting device. If it's a mobile device, send the request to the destination in the Redirect behavior. However, don't redirect if a cookie or query string parameter requests the desktop site.

Mobile Detection & Redirect with Desktop Cookie logic

First, if a query string parameter requests desktop site, don't redirect. Otherwise:

  • If a cookie requests the desktop site, don't redirect. But if there is a query string parameter, it cannot request the desktop site (see previous rule) and so must request the mobile site; apply redirect as described below. If both a query string parameter and a cookie exist and they conflict, obey the query string parameter.

    • If the request passes all of the rules mentioned above, identify the device. If it's a mobile device, send the request to the destination in the Redirect behavior. If not, don't redirect.

    • If the request passes all of the criteria to this point, any desktop cookie that is still present is in conflict with a query string parameter. Remove this cookie by setting its expiration date in the past.

  • If a query string parameter requests the desktop site, set a desktop cookie.

  • If a cookie requests the desktop site and there is no desktop query string parameter, reset the cookie's expiration time.

Mobile Detection & Redirect with Usablenet logic

This template is intended for sites with Usablenet, a third-party mobile site hosting service. Other than the following two differences, the logic is identical to that for the Desktop Cookie template.

  • The template already includes the correct desktop cookie name and value (stop_mobi and yes).

  • The first match criterion in the template includes a condition to be compatible with Usablenet.

MD&R: Best practices

Test match criteria

When configuring match criteria, you may want to review the values returned for the device characteristics you plan to use. To do this, click the help link in any device characteristics match criteria. Scroll down to the User Agent Lookup tool. Enter a complete user-agent string in the field, and click Run Lookup. The values returned display in a separate results screen.

You can find user-agent strings here:


If the lookup doesn't detect a device for the user agent string entered, the results screen will display, but without any values.


If you notice an error on the results screen, please open a Support Case that includes the UA string entered and the output of the lookup. An example of a lookup error is when you enter the UA string of a tablet device, and the lookup returns a false value for the is_tablet characteristic.

Check case sensitivity

In match criteria, the case sensitivity settings can affect the results. Check that case sensitivity is correct for each criterion by clicking the gear symbol.

Break up long match criteria values

It is possible for some match criteria values to be too long to fit in the condition field (for example, a very long path). You can still create a match on such a value by adding multiple match criteria conditions, each with a portion of the string you want to match.

MD&R: Definitions

  • MD&R Rule. A user-defined setting that specifies which requests MD&R redirects, where to
    redirect them, and (if applicable) how to manage desktop cookies and desktop query
    strings. Like other rules, an MD&R rule consists of two parts: match criteria and behaviors.


The order of rules is important: The last applicable rule wins. Therefore, you should order your rules from least specific at the top to most specific at the bottom. If the request doesn't match any of the rules on the list, then the resource specified in the original request is sent to the device.

  • Behavior. An instruction that tells the edge server how to handle requests. In MD&R, the main
    behavior you use is Redirect, which defines where a mobile request should be sent.
    The Redirect behavior also lets you to establish exceptions that will prevent a request
    from being redirected.

  • Match Criteria. The conditions under which a rule's behavior(s) should apply. In MD&R, the match
    criteria compare attributes of the requesting device or the incoming request to these
    user-defined conditions. MD&R match criteria include a special set of device
    attributes that use the device characteristics library.

  • Device characteristics library. A collection of several attributes of most devices on the market developed
    from a combination of device user-agent strings, an industry-standard database (WURFL),
    and internal device monitoring capabilities. The edge server uses this library to identify
    a requesting device's characteristics. You can find more information about the device characteristics
    in the MD&R: Device characteristics table.

  • User-agent string. A unique device identifier contained in HTTP request.

  • Desktop cookie. Data stored on an end-user's browser that indicates whether the user selected the
    desktop (non-mobile) version of your site. A common implementation involves a link or
    button on your mobile site labeled "Go to Desktop Site" (or similar). Clicking it creates
    the desktop cookie on that user's browser, which returns the cookie with requests for your
    site's content. The desktop cookie maintains a user's site preference until the cookie
    expires. If your site uses desktop cookies, we recommend that you configure MD&R not
    to redirect requests from users who have requested the desktop site.

  • Desktop query string. Similar in function to a desktop cookie. The main difference is in the implementation:
    Instead of reporting the user's site preference in a cookie, the information is sent as
    part of the requested URL. If your site uses desktop query strings, we recommend that you
    configure MD&R not to redirect requests from users who have requested the desktop site.

MD&R: Device characteristics table

CharacteristicData TypeDescription
resolution_height resolution_width integerThe screen height/width, measured in pixels.
physical_screen_height physical_screen_width integerThe height/width of the screen, in millimeters.
rows integerThe number of viewable lines.
max_image_height max_image_width integerThe maximum height/width, in pixels, for an image to be viewable when the page renders in a mobile-optimized format.
columns integerNumber of columns the device can display.
pointing_method joystick, stylus, touchscreen, clickwheel, "" (empty string)The mechanism for device navigation.
device_os stringThe requesting device's operating system (for example, Android, iOS, Windows 7).
device_os_version stringThe request device's operating system version.
mobile_browser stringThe requesting device's browser.
mobile_browser_version stringThe version of the requesting device's current mobile browser.
model_extra_info stringAdditional model information such as features appended to the marketing name (for example, 4G).
brand_name stringDevice maker (for example, Samsung, Apple).
model_name stringRequest device's model (for example, SCH-I110)
marketing_name stringThe device model's commercial name (for example, Samsung Illusion).
device_claims_web_support true/falseIndicates if the requesting device's browser supports web-optimized content.
streaming_video true/falseIndicates if the requesting device supports streamed video.
pdf_support true/falseIndicates if the requesting device can read PDF files.
dual_orientation true/falseIndicates if the requesting device can rotate displayed content, which swaps the height and width dimensions.
ajax_support_javascript true/falseIndicates if the requesting device supports JavaScript.
cookie_support true/falseIndicates if the requesting device's browser supports cookies. However note that cookie support does not indicate that the cookies exist. Also, even if the native browser does not support cookies, they might be supported via other methods.
is_mobile true/falseIndicates if the requesting device is a mobile device.
is_smarttv true/falseIndicates if the requesting device is a SmartTV (for example, AppleTV).
is_tablet true/falseIndicates if the device is a tablet; this is a subcategory of mobile device.
unique true/falseIndicates if the user agent of the requesting device is device specific. If false, the same user agent is used for multiple devices.