detectmyPhone Documentation

Last updated: June 16th 2010 - Click here to go to the main detectmyPhone site

1 line of Javascript you say??

Yep! It's that easy! Typically all you need to do is add something like this between <header> and </header> tags in your website html:


Code:

  <script type="text/javascript" src="http://kramerican.dk/detectmyphone/handsetdetect-latest.js?websiteID=XX-XXXXXXX-XX"></script>

Where websiteID=XX-XXXXXXX-XX should be replaced with a website profile ID that you generate in our backend systems when you've signed up for detectmyPhone.
You can even generate a detection script customized for your own site and host it yourself, so you're not dependent on our crappy servers (hey, this thing is 100% free - it's not like we're using fancy Amazon cloud computing here...)

Javascript Integration options

We've added a few integration options that you can use to get more flexibility. detectmyPhone can either redirect the user to a URL of your choosing, or execute arbitrary Javascript that you define in our back-end (you can read up on how to do this in the Using the Dashboard section of this doc). Due to this (awesome) flexibility there are a couple of advanced options you can use:

How can I stop detectmyPhone from redirecting users?
There are cases where you don't want to redirect users to a mobile friendly site - for example mobile users who don't wish to view the mobile version of your site.
This behavior is not built into the main detectmyPhone script - So there are two ways of achieving this: 1) Using serverside scripting or 2) Using some Javascript magic. #1 is simpler coding wise, and might be a tad more reliable whilst #2 requires no knowledge of any serverside scripting stuff, so this might be preferable to most users of detectmyPhone

These examples assume that the querystring you are using is called "show=fullsite" e.g. http://www.mysite.com/somepage.php?show=fullsite

Example of using Serverside scripting (PHP in this case) to stop detectmyPhone from loading depending on a querystring:
This example approach uses the session variable to enable persistency


Code:

if($_GET['show'] == "fullsite") {

 //We got the "fullsite" directive from our querystring, so we save this in our session for future reference
    $_SESSION['show'] = $_GET['show'];
  
 } else {

 //Check if we have something saved in our session variable
   if ($_SESSION['show'] != "fullsite") {  
 //No mention of "fullsite", so there is nothing to stop us from loading detectmyPhone
    echo('<script type="text/javascript" src="http://kramerican.dk/detectmyphone/handsetdetect-latest.js?websiteID=XX-XXXXXXX-XX"></script>');

   }  

 }

Example of using our Javascript helper script to stop detectmyPhone from loading depending on a querystring - You can view the source by downloading the helper js
WARNING: Using this approach has the drawback that your regular website will fully load before detectmyPhone can do a redirect to the mobile version of your site. To avoid this you will need to use the serverside scripting approach.


Code:

<script type="text/javascript" src="http://kramerican.dk/detectmyphone/handsetdetect-helper.js"></script>

<script language="JavaScript" type="text/javascript">

 //Conditionally load detectmyPhone if show=fullsite is not found in page querystring
 cond_load_demyphone("XX-XXXXXXX-XX","show","fullsite",true);

</script>

How does the function cond_load_demyphone work?
The function cond_load_demyphone is located in handsetdetect-helper.js and conditionally loads detectmyPhone and adds persistency by the use of cookies. The function is defined as follows:
Function cond_load_demyphone(websiteid,variable,fullvalue,persistency);
websiteid - (string) This is your website profile ID which you get through our back-end dashboard when you set up a website profile.

variable - (string) This is whatever you call your querystring variable which governs whether detectmyPhone should load or not (example: "show")

fullvalue - (string) This is the value of your querystring variable which should prevent detectmyPhone from loading (example: "fullsite"). If you set the querystring variable to anything else, such as "mobilesite" then detectmyPhone will load and do its thing

persistency - (boolean) This variable tells the helper script whether it should save the last querystring value in a cookie, and in this way "remember" whether to load detectmyPhone or not. Saves you the trouble of adding "show=whatever" to all your links on your site.

If used as in the example above, you could now switch between your full website and your mobile website on a smartphone handset by visiting your site like so:
http://www.mysite.com/somepage.php?show=fullsite - Would show the full website
http://www.mysite.com/somepage.php?show=mobilesite - Would show your mobile website

Waiting untill your page is fully loaded before running detectmyPhone
Usually detectmyPhone executes the rules you define in the Dashboard as soon as the script is loaded. However, you can tell detectmyPhone to generate a detection script which executes after your page has been fully loaded - this could come in handy if you are running your own custom javascript, and not doing a redirect. To do this, you have to include the detectmyPhone script like so:


Code:

  <script type="text/javascript" src="http://kramerican.dk/detectmyphone/handsetdetect-latest.js?websiteID=XX-XXXXXXX-XX&onpageload=true"></script>

Note the &onpageload=true option at the end of the detection script URL. If you want to host the detectmyPhone script on your own server with this behavior, you need to 1. define all your rules in the Dashboard and then 2. download the detectmyPhone script and pass this option

Using the callback function to get notified of detectmyPhone finishing its work
The detectmyPhone can call a function in your host document to notify the page that it's finished doing its work. All you need to do to get this working is define the callback function (demyphonePing()) in the host webpage like so:


Code:

	function demyphonePing() {

	 alert("We got a pingback from detectmyPhone");

	}

Using the Dashboard

Using the Dashboard should be dead-easy. If we are confusing you, let us know and we will see what we can do to improve the UI. Also, if you see any weird bugs don't hesitate to get in touch with us!

Adding / editing website profiles
Before you can get started defining what happens when a user visits your website with a particular handset, you need to add it as a website profile. This is a required step in order to assign your website a unique ID so that detectmyPhone knows what to do when it starts working on your site. Simply enter your website domain name - e.g. "kramerican.dk" (there is no need to include www. or other subdomain information)

Managing detection rules
When you've added a website profile you should see the following in the "Your Website Profiles" overview:

This list the domain you're creating detection rules for, and what its Website Profile ID is along with misc. options:
Show Javascript Code
Clicking on this link pops a friendly page showing you the javascript you need to include in your website header to get detectmyPhone working on your site.

Delete
Does what it says: This option deletes the website profile along with ALL defined detection rules. Don't worry, you can always recreate the Website profile - just remember to grab the newly generated Javascript Code if you do so.

Click here to Manage
Clicking this option will highlight your selected website profile in green, and show you all the good stuff - that is the detection rules management:

Here you can define what should happen when a user visits your website using a specific handset. As you can see in the screenshot above we've defined two rules, one for iPhone and another for Android devices.
Once you've added a rule you cannot edit it. You will have to delete an existing rule and re-create it if you wish to make changes to it.
To add a new detection rule follow these steps:

Select a handset to detect from the first dropdown menu
This will tell detectmyPhone which handset the rule you are about to create should apply to.

Select what detectmyPhone should do: redirect the user or execute some javascript
In the next dropdown you select whether you want a plain old redirect to a smartphone-friendly site of your choosing - or whether you want to run some javascript on your host page.

Enter a redirect URL or add some javascript
Depending on which option you will choose the UI will change and give you a self explanatory edit field or a link to pop a text editor where you can insert your Javascript.
For example, you might need something like this:


Code:

if(confirm('Hello - I see you are using and Android handset - hit OK to see the iPhone site, or hit Cancel to see our regular website.')) {

  window.location='http://iphone.kramerican.dk';

}

WARNING: detectmyPhone makes no attempt at validating your Javascript. If it breaks your page or the smartphone detection - heck, you can't blame us. Test your script thoroughly before inserting it as a rule.

Finally click Add detection rule and you're set to go!
You can even add multiple rules for the same type of smartphone handset. We're not sure why you would want to do so - but we sure as heck won't stop you!

Supported handsets & compatibility

detectmyPhone should work well in all major browser and play well with other Javascript libraries such as jQuery etc. - If you encounter weirdness and/or funkyness however, please don't hesitate to contact us!

Most of the info in this section is shamelessly stolen from www.hand-interactive.com - Thanks guys!

detectmyPhone is free, semi-open-source (the javascript is free for inspection / modification, our backend Dashboard management system is not) - so it comes with a few caveats:

Users can turn off JavaScript in their browsers. If it's off, detectmyPhone won't work.
Some mobile browsers don't support JavaScript, especially on older or more basic mass market devices.
When a mobile browser only supports Wap/WML, it probably doesn't support JavaScript. (Which includes BlackBerries in WML mode.)
detectmyPhone depends on the contents of the UserAgent string. As a result, these techniques may not work when the browser is emulating another (e.g., some mobile browsers can be set to emulate Internet Explorer).
Mobile operators can also change the UserAgent contents when the device is customized for their networks and added to their stock device portfolio.

With these things in mind however, detectmyPhone will work just nicely in 90%+ of all cases. Currently detectmyPhone is tested to detect the following smartphone handsets:

iPhone & iPod Touch
Mobile Safari is based on WebKit and can render most desktop-targeted web content very well (generally excluding heavy AJAX pages). Don't send users to barebones WAP/WML pages! Instead, give iPhone users regular desktop pages, iPhone-optimized content or nicely formatted mobile-optimized content.

Symbian S60 Smartphones
The most popular smartphone platform in the world is Symbian S60. Used primarily by Nokia and a few other manufacturers, S60 features an extremely capable browser.

Why detect this browser? Users with S60 phones as a group are the largest consumers of the mobile web. Similar to the iPhone, the S60 Open Source Browser is based on WebKit and can render most desktop-targeted web content very well (generally excluding heavy AJAX pages). Don't send users to barebones WAP/WML pages! Instead, give S60 users regular desktop pages or nicely formatted mobile-optimized content.

Android Devices
Android is a smartphone-class OS with an advanced browser that is similar to Mobile Safari on the iPhone in capabilities.
We added two new methods to the JavaScript code to detect for Android phones. The first detects simply whether the device is running the Android OS. The second detects whether the browser is based on WebKit (like Mobile Safari). The second method may become important in the future as other web browser companies start to release browsers for Android.

Why detect this browser? The native Android browser is extremely capable and also based on WebKit, which underlies Mobile Safari & the S60 browser.

Windows Mobile Devices
Devices running Windows Mobile are fairly popular in the U.S., especially among corporate IT departments. This code should detect both the non-touch screen (Standard/Smartphone) and touch screen (Professional/PocketPC) types of devices.

Why detect this browser? Pocket Internet Explorer and Opera for Windows Mobile are moderately capable mobile browsers. Don't send users to barebones WAP/WML pages! Instead, give these users either modest desktop pages (avoid AJAX and complicated CSS) or nicely formatted mobile-optimized content. (The latter is probably the better choice.)

BlackBerry Devices
The most popular smartphone platform in the United States. (Still beats the iPhone in sales!) Unfortunately, the BlackBerry browser isn't great. The browser can be set to WML-only mode, HTML only, or both. Goodness knows why it needs this many options and isn't always on auto-detect. Because of this little "feature", JavaScript-based detection isn't reliable if you need to know that it's a BlackBerry. Then again, if the device is set to WML mode, then that's what you should give it.

Why detect this browser? Although the browser isn't as capable as the WebKit ones noted above, it can display nicely (but minimally!)-formatted mobile-optimized content. At least when the browser is set to HTML mode! Otherwise, in WML-only mode, it should be sent the barebones WAP/WML pages.

PalmOS Devices
These devices are still fairly popular in the U.S., if less so abroad, and there is a large installed base of PalmOS devices.

Why detect this browser? As the device which practically invented the smartphone category, PalmOS devices ship with a browser and a good number of users have data plans. Unfortunately, we don' t have a PalmOS device in our device library yet, so we can't make any content format recommendations.

Source code and contribution

The generated detectmyPhone javascript is licensed according to the Creative Commons Attribution 3.0 License (http://creativecommons.org/licenses/by/3.0/) - This basically means that you should give props where props are due.
With this in mind, then our backend Dashboard management system is closed-source (for now). So if you want to contribute, then it would primarily be in adding more detection logic to the detectmyPhone javascript and eradicating any pesky bugs that might be lurking.
To take a look at the source, simply sign up for our service and download the script. If you want to contribute with fixes or additions, simply be in touch and we will holla at ya (hmm...holla?).

Need more help? Be in touch!

If you need further help, then the only way (for now) is to mail us at demyphone (@) kramerican (.) dk - We will probably set up a forum one of them days to make contribution and communication a bit more streamlined.

Copyright / Disclaimer etc.

The generated detectmyPhone javascript is licensed according to the Creative Commons Attribution 3.0 License (http://creativecommons.org/licenses/by/3.0/)
The back-end Dashboard is closed source (for now) and is copyright (c) 2010 - 2199 (we plan on living a long long time) Kramerican Industries.
We guarantee nothing using this software. If we break your site, too bad - this is free software which may or may not have been tested by feral monkeys in a lab somewhere. So use with caution and care!

Thanks for sticking with us to the end! - The Kramerican Industries crew