Safari on iPhone and iPod touch uses the same Web Kit engine as Safari on the computer desktop. With the Safari Web Kit engine, you can develop sophisticated Web 2.0 sites and applications that impress and delight iPhone users. To design a web application that shines on iPhone and ensures a great user experience, you’ll want to:
- Understand the capabilities of iPhone
- Follow established design practices for the web
- Adopt iPhone-specific design principles
The following guidelines will help you prepare web content and design a website or web-based application for iPhone. If you are a seasoned web developer, there are probably just a few refinements you can make to ensure that your site looks great and works best on iPhone. You’ll need to read only those guidelines that are unique to iPhone. If you are fairly new to web development, you’ll want to make sure that you understand web standards and established web design best practices before following any iPhone-specific guidelines.
Note: Safari on iPhone behaves the same on iPhone and iPod touch except when the user taps links to iPhone-only applications.
Understand User-iPhone Interaction
It’s tempting to think that using an iPhone is like using a computer. But it isn’t. There are a few differences that make user interaction with iPhone unique and that you’ll want to keep in mind as you design web content according to the guidelines described throughout this document.
Know the Input Device
iPhone users supply their own input device — two fingers. Fingers come in all sizes and shapes, from the thin, pointy model to the thick, rounded one. Yet, webpages are designed to receive mouse events, not finger events. Existing pages need to continue to work as expected even with the finger as an input device.
Fingers don’t have the precision of the pointer controlled by the mouse. They also have different capabilities than those of a mouse. For example, fingers can pinch; a mouse can click. The differences between fingers and the mouse have implications for how events are propagated to webpages and for hit regions, as explained in “Know Which Events You Can Handle” and “Design for Double Tap.”
The following table lists the actions and results of using fingers as an input device.
| Gesture | Result |
|---|---|
| Double tap | Zoom in and center a block of content |
| Touch and hold | Display an information bubble |
| Drag | Move the viewport or pan |
| Flick | Scroll up or down (depending on the direction of the finger movement) |
| Pinch open | Zoom in |
| Pinch close | Zoom out |
A few other things to keep in mind about fingers as an input device:
- There are no gestures to perform cut, copy, paste, drag-and-drop, and text selection operations.
- The width of a finger limits the density of links on a page. If the links are too close, your users won’t be able to choose a single one.
Think Windowless
Computer users frequently resize and move web browser windows. Safari on iPhone doesn’t have windows; it has a fixed viewport. As such, iPhone does not provide scroll bars or resize controls. Instead, it automatically scales content to fit, and it allows users to zoom in content to focus on a particular area using the gestures above, as explained in “Lay Out Content for iPhone Viewport” and “Adjust Text Size for Readability.”
Design for Double Tap
When the user double-taps a page, Safari on iPhone looks at the element that is double-tapped, and finds its closest block (as identified by elements like <div>, <ol>, <ul>, and <table>) or the image element (<img>) ancestor. If the found element is a block, Safari on iPhone zooms the content to fit the device width and then centers it. If it is an image, Safari on iPhone zooms to fit the image, and then centers it. If the block or image is already zoomed in, Safari on iPhone zooms out.
If you have an existing page, you don’t need to modify your site except for the layout. The best layout is a simple block structure throughout the page, preferably one that uses columns and that organizes content into digestible sections.
Avoid wide blocks of text because these can’t be zoomed in a way that allows users to view the contents without the need to use a finger to scroll the page back and forth.
Know Which Events You Can Handle
See "Handling Events" in "Safari Web Content Guide for iPhone" for the events generated by iPhone gestures. There's a onorientation event generated when the user swithces from portrait to landscape and vice versa.
Use Standards and Tried-and-True Design Practices
Integrate with Phone, Mail, Maps, and YouTube
Safari on iPhone can seamlessly integrate with other iPhone applications to provide a rich user experience. You access other functionality by adding these kinds of link elements to webpages:
-
Telephone links.
A link to a phone number looks like this:
<a href="tel:1-408-555-5555">1-408-555-5555</a>
If you don’t wrap phone numbers in a link, Safari automatically converts any number that takes the form of a phone number to a telephone link. If your page contains a series of numbers that could be interpreted as a phone number, but isn’t, you can turn this feature off.
-
Mail links open a built-in mail compose sheet.
<a href="mailto:frank@wwdcdemo.example.com">John Frank</a>
-
Google maps links open a built-in Google client rather than making a connection through the public website.
This link opens to a point on a map (Cupertino, California):
<a href="http://maps.google.com/maps?q=cupertino">Cupertino</a>
This link provides directions between two points, San Francisco and Cupertino:
<a href="http://maps.google.com/maps?daddr=San+Francisco,+CA&saddr=cupertino">Directions</a>
For a description of YouTube links, see "Using iPhone Application Links" in "Safari Web Content Guide for iPhone."
Remember that users tap with a finger to choose a link. If you put links too close together on a page, your users may not be able to select the one they want.
Optimize for Page Readability
By following some simple strategies for laying out content, adjusting text size, optimizing images, and the like, you can make your web application look great and perform well on iPhone.
Know Where Your Pages Are Rendering
The Safari user agent string for iPhone is similar to the user agent string for Safari on the other platforms except for two differences: it contains an iPhone platform name and the mobile version number. The platform name for Safari on iPod touch is iPod.
Mozilla/5.0 (iPhone; U; CPU like Mac OS X; en) AppleWebKit/XX (KHTML, like Gecko) Version/ZZ Mobile/WW Safari/YY
For each, "XX" is the build version of the web technology framework used by Safari and "YY" is the build version of the Safari application. Safari 3 on iPhone contains the additional "Mobile/WW" portion in the user-agent string - where "WW" is the operating system version number. Safari 3 or greater on all platforms contains the additional "Version/ZZ" portion in the user-agent string - where "ZZ" is the Safari family version number.
A sample platform string is: (iPhone; U; CPU like Mac OS X; en)
A sample version string is: Version/3.0 Mobile/1A543a Safari/419.3
The marketing version (Version/3.0), for example, is included in Safari on other platforms. Therefore, you can use it to track usage statistics across all platforms.
For more information on the user agent and object detection, see:
- http://trac.webkit.org/projects/webkit/wiki/DetectingWebKit
- http://developer.apple.com/internet/webcontent/objectdetection.html
- http://developer.apple.com/internet/safari/faq.html#anchor2
Specify an iPhone Style Sheet
Web designers often assume a particular window size when designing their sites. If that’s the path you want to take, you may want to provide one for a Safari on iPhone specific size. You should also provide conditional CSS for iPhone (or other devices, for that matter).
You can tailor the style of your webpages by providing a style sheet that adapts to iPhone. The CSS 3 media query allows you to do just that. There are several types of queries including print, handheld, and screen. iPhone ignores the print and handheld media queries because these types do not supply high-end content. So the screen query is what you need to use.
To specify a style sheet that is just for iPhone without affecting other devices, you use the only keyword in combination with the screen keyword, as follows:
<link media="only screen and (max-device-width: 480px)" href="small-device.css" type="text/css" rel="stylesheet" >
Older browsers ignore the only keyword and won’t read your iPhone style sheet. To specify a style sheet for devices other than iPhone, use an expression similar to the following:
<link media="screen and (min-device-width: 481px)" href="not-small-device.css" type="text/css" rel="stylesheet" >
For more information on media queries, see:
Lay Out Content for the iPhone Viewport
The viewport is the rectangle area that determines how content is laid out and where text wraps on a webpage. On the desktop, the viewport is determined by the size of the window. The user resizes the viewport by resizing the window and scrolls to see more of the webpage. Safari on iPhone doesn't have windows — there are no scroll bars or resize knobs. Therefore, the "window" is a fixed size determined by the iPhone screen size. The user pans to see more of the webpage, and can also zoom in and out using double tap or the pinch gesture.
To make this work on iPhone, the viewport has a scale, width, and height property. When Safari first loads a webpage, it sets the initial scale to fit the webpage completely width-wise on the iPhone screen. Safari on iPhone also sets the viewport width to 980 pixels, the width of most webpages. If these default values don't work for your content, you can change them and other viewport properties using the viewport meta tag in your content.
For example, if your webpage is less than 980 pixels wide, causing it to scale too small on iPhone, then set the viewport width to the width of your webpage. Note that the width of your content can always be greater than the viewport width — requiring the user to pan to see more content. The initial scale property only controls the scale when the webpage is first displayed. Thereafter, the user controls the scale using gestures. So if you don't want the user to scale your content, use the viewport meta tag to turn off user scaling of your content.
The viewport meta tag properties are:
widthThe default is980. The range is[200, 10,000].heightThe default is calculated based on the width and aspect ratio. The range is[223, 10,000].initial-scaleis the scale to render the page when it first loads. The default fits the page to the screen. The range is[minimum-scale, maximum-scale]. Keep in mind that the user can change the scale, either through the pinch gesture or by a double tap.user-scalabledetermines whether or not the user can scale the page. The default isyes.minimum-scaleis the lower bound for scaling. The default is0.25; the range is[>0, 10].maximum-scaleis the upper bound for scaling. The default is1.6; the range is[>0, 10].
You do not need to set each property. If only a subset of the properties are set, then Safari on iPhone attempts to infer the other values. For example, if you set the scale to 1.0, Safari assumes the width is 320 pixels in portrait and 480 pixels in landscape orientation. Therefore, if you want the width to be 980 pixels and the initial scale to be 1.0, then set both of these properties.
Here are some examples of using the viewport meta tag:
<meta name="viewport" content="width = 320" /> <meta name="viewport" content="initial-scale=2.3, user-scalable=no" />
Use the device-width and device-height constants to specify the device dimensions, not 320 and 480 respectively.
The recommended viewport width for web applications is device-width. This renders the web application with a scale of 1.0 and doesn't change the layout when you switch to landscape orientation.
Adjust Text Size for Readability
Safari on iPhone adjusts the text size so it's more readable after the user double taps. After a double-tap, Safari on iPhone gets the width of the block of text and determines the width after a double-tap. Safari on iPhone then determines an appropriate multiplier that is applied to the layout.
Sometimes you might find that automatic text size adjustment doesn't produce ideal results. For example, text in absolute-positioned elements might overflow the viewport after adjustment. Other pages might need a few minor adjustments to make them look their best. In these cases, you can override the text size adjustment.
Use the -webkit-text-size-adjust CSS property to override Safari’s default text size adjustment. The values for -webkit-text-size-adjust are:
- none:
<body style="-webkit-text-size-adjust:none"> - auto:
<table style="-webkit-text-size-adjust:auto"> - multiplier percentages:
<div style="-webkit-text-size-adjust:200%">
Optimize Images
Safari on iPhone supports these image formats:
- GIF
- PNG
- TIFF
- JPG
The maximum decoded image size for GIF, PNG, and TIFF images is 2 megapixels. That is, ensure that width * height &le 2 * 1024x1024. The decoded size of animated GIF images must be less than 2 MB. For large animated GIFs, only the first frame is shown.
The maximum decoded image sizes for JPG images is 32 megapixels (due to subsampling), which allows JPG images to decode to a size that has 16 times fewer pixels. JPG images larger than 2 megapixels are subsampled — that is, decoded to a reduced size. JPG subsampling allows users to view images from the latest digital cameras.
If you include very large images on your pages, Safari on iPhone might alter the layout of the page to accommodate the smaller size. For best results, you should supply reduced size images.
Also keep in mind the size limits for resources, which includes the encoded image size. See “Resource and Execution Limits.”
Lay Out Forms Appropriately
If your webpage uses forms, it helps to know the layout of the keyboard and other controls used to submit forms on iPhone. The available area for your web content changes depending on whether or not the keyboard is displayed. You should compute this area and design your forms accordingly.
The status bar that appears at the top of the screen contains the time and Wi-Fi indicator. The URL text field is displayed below the status bar. The keyboard is used to enter text in forms and is displayed at the bottom of the screen. The form assistant appears above the keyboard when editing forms. It contains the Next, Previous, and Done buttons. The user taps the Next and Previous buttons to move between form elements. The user taps Done to dismiss the keyboard. The button bar contains the back, forward, bookmarks, and tabs buttons and appears at the bottom of the screen. The button bar is not visible when the keyboard is visible. Your webpage is displayed in the area below the URL text field and above the button bar or keyboard.
The heights of the iPhone controls are as follows:
- Status bar: height=20 pixels
- URL text field: height=60 pixels
- Form assistant: height = 44 pixels
- Keyboard: portrait height=216 pixels, landscape height=180 pixels
- Button bar: portrait height=44 pixels, landscape height= 32 pixels
Use this information to compute the available area for your web content when the keyboard is and isn't displayed. For example, when the keyboard is not displayed, the height available for your web content is: 480 - 20 - 60 - 44 = 356. Therefore, you should design your content to fit within 320 x 356 pixels in portrait orientation. If the keyboard is displayed, the available area is 320 x 140 pixels.
For more information about the way Safari on iPhone displays form controls, see "Accommodate the Built-in Form Interface" in "iPhone Human Interface Guidelines."
Design Custom Form Controls Appropriately
For more information, see "Metrics, Layout Guidelines, and Tips" in "iPhone Human Interface Guidelines."
Use Appropriate Metrics for List Layouts
Often, a webpage displays information in a list-like format, such as a list of RSS feeds. Depending on the organization of your content, you can use a simple list layout that displays all items in equally sized rows or you can use a rounded rectangle layout to group subsets of items. Note that although grouping items allows you to display your content in a hierarchical way, you should avoid showing more than two levels of hierarchy in a single layout, because deeply nested items are difficult for the user to select. For more information about list layouts and other design guidelines, see "Metrics, Layout Guidelines, and Tips" in "iPhone Human Interface Guidelines."
To display a simple list of items use the edge to edge design, which yields the most space for your content. Each row, or cell, is 44 pixels high (including the line at the bottom of the cell) and 320 pixels wide. Use Helvetica 20px in black for all text. By default, you should make your text bold for optimum readability, but you can use regular font for content that's less important. The background fill color of the list is white and the lines between items are R=217, G=217, B=217. Text should be inset 10 pixels from the left edge and 14 pixels from the line at the bottom edge of the cell.
If you need to provide a control, design a rounded rectangular button that is 29 pixels high and has a corner radius of 5 pixels; Use Helvetica 12px for the text you display on the button. Place the button 10 pixels from the right edge of a cell and center it vertically.
To display items in groups, use the rounded rectangle design. Each rounded rectangle has a corner radius of 8 pixels, a width of 300 pixels, and white background fill. The edges of the rounded rectangles and the horizontal lines between the cells inside them are R=217, G=217, B=217. Because there is slightly less space for content in this design, use Helvetica 17px in black for all text. As with the edge to edge design, you should use bold font by default, but you can use regular font for secondary content. Within a rounded rectangle, text should be inset 10 pixels from the left edge and 14 pixels from the bottom edge of a cell.
A rounded rectangle should be inset 10 pixels from both right and left edges of the iPhone screen and 17 pixels from the top of the button bar.
This design allows you to display text between the rounded rectangles that you can use as labels for the content. This text should be Helvetica 17px and should be bold. Instead of black, however, the color of this text is R=76, G=86, B=108. The size of the area behind the rounded rectangles is 320 pixels wide and 356 pixels high and its background fill color is R=197, G=204, B=211.
Ensure a Great Audio and Video Experience
iPhone streams movies and audio using HTTP over EDGE and Wi-Fi networks. To deliver the best web audio and video experience on iPhone:
- Encode H.264/AAC at appropriate sizes and bit rates for EDGE and Wi-Fi networks. See “Encode Video for Wi-Fi and EDGE.”
- Use reference movies so that iPhone automatically streams the best version of your content for the current network connection. See “Create a Reference Movie.”
- Make sure the HTTP servers hosting your media files support byte-range requests. See “Configure Your Server.”
- Follow current best practices for embedding movies in webpages.
- Use poster JPEGs (not poster frames in a movie) to display a preview of your embedded movie in webpages. See “Embed Movies in Webpages.”
- If your site has a custom media player, also provide direct links to the media files. iPhone users can follow these links to launch directly into playback.
- Don’t bring up JavaScript alerts that ask users to download Flash. Flash isn’t supported and neither are file downloads.
- Don’t use JavaScript movie controls to play video on iPhone. iPhone supplies its own controls.
Encode Video for Wi-Fi and EDGE
You can use the QuickTime Pro v7.2 Export command and the following exporters to prepare video content for iPhone:
- "Movie to iPhone" prepares movies for Wi-Fi.
- "Movie to iPhone (Cellular)" prepares movies for EDGE.
For QuickTime Pro v7.1.6 and earlier, use these exporters and settings:
- The Movie to MPEG-4 exporter with the following settings prepares movies for Wi-Fi.
In the H.264 video options, make sure you restrict the encoder to use the Baseline profile, and select "Faster encode (Single-pass)" encoding in the Video Options dialog.
Video settings: 900 kbit/sec, H.264, 480 x 360; frame rate: current; preserve aspect ratio using: Fit within size
Audio settings: 128 kbit, AAC-LC
.mp4 file - The Movie to 3G exporter with the following settings prepares movies for EDGE.
Video settings: 64 kbit, H.264, 176 x 144; frame rate: 10 or 15; preserve aspect ratio using: Letterbox or Crop
Audio settings: 16 kbit, AAC-LC
.3gp file
In each of the QuickTime Pro v7.1.6 and earlier exporters, turn off streaming; iPhone does not stream media using RTP/RTSP.
Size Movies Appropriately
In landscape orientation, the iPhone screen is 480 x 320 pixels. Users can easily switch the view mode between scaled-to-fit (letterboxed) and full-screen (centered and cropped). You should use a size that preserves the aspect ratio of your content and fits within a 480 x 360 rectangle. 480 x 360 is a good choice for 4:3 aspect ratio content as it will keep the video sharp in full-screen view mode.
Don’t Let Bit Rate Stall Your Movie
When viewing media over the network, bit rate makes a crucial difference to the playback experience. If the network cannot keep up with the media bit rate, playback stalls.
Use Supported Movie Formats
The following movie formats are supported:
- H.264 Baseline Profile Level 3.0 video, up to 640 x 480 at 30 fps. Note that B frames are not supported in the Baseline profile.
- MPEG-4 Part 2 video (Simple Profile)
- AAC-LC audio, up to 48 kHz
- .mov, .mp4, .m4v, .3gp file formats
- Any movies or audio files that can play on an iPod.
Create a Reference Movie
A reference movie contains a list of movie URLs, each of which has a list of tests. When opening the reference movie, a playback device or computer chooses one of the movie URLs by finding the last one that passes all its tests. Tests can check the capabilities of the device or computer, and the speed of the network connection.
For more details on reference movies and instructions on how to set them up see Applications and Examples in HTML Scripting Guide for QuickTime.
See the MakeiPhoneRefMovie sample for a command-line tool that creates reference movies.
You can download the MakeRefMovie tool from:
http://developer.apple.com/quicktime/quicktimeintro/tools/index.html
Configure Your Server
HTTP servers hosting media files for iPhone must support byte-range requests, which iPhone uses to perform random access in media playback. (Byte-range support is also known as content-range or partial-range support.) Most, but not all, HTTP 1.1 servers already support byte-range requests.
If you are not sure whether your media server supports byte-range requests, you can open the Terminal application in Mac OS X and use the curl command-line tool to download a short segment from a file on the server:
curl --range 0-99 http://example.com/test.mov -o /dev/null
If the tool reports that it downloaded 100 bytes, the media server correctly handled the byte-range request. If it downloads the entire file, you may need to update the media server. For more information on curl, see Mac OS X Man Pages.
Ensure that your HTTP server sends the correct MIME types for movie family file suffixes shown in the following table.
| File name suffix | MIME type |
|---|---|
| .mov | video/quicktime |
| .mp4 | video/mp4 |
| .m4v | video/x-m4v |
| .3gp | video/3gpp |
Be aware that iPhone supports movies greater than 2 GB. However, some older web servers are not able to serve files this large. Apache 2 supports downloading files greater than 2GB.
RTSP is not supported.
Embed Movies in Webpages
iPhone does not decode video until the user enters movie playback mode. This means that when displaying a webpage with embedded video, users see a gray rectangle with a QuickTime logo until they press the Play button. For example, provide a preview image that will be displayed in the webpage, specify the image as the src, the movie as the href, the media MIME type as the type, and "myself" as the target:
<embed src="poster.jpg" href="movie.m4v" type="video/x-m4v" target="myself" scale="1" ...>
In desktop web browsers, this image is displayed until the user clicks, at which time the movie is substituted.
For more information on including QuickTime Movies in webpages, see: Including QuickTime in a Webpage.
Know What Safari Supports on iPhone
While Safari on iPhone uses the same Web Kit engine as Safari on the computer desktop, iPhone has unique user interaction features appropriate for a portable device. You need to work within the feature set available with Safari on iPhone, and you should provide work-arounds for Safari features unavailable on iPhone.
Resource and Execution Limits
Any downloaded resource, whether it’s HTML, CSS, JavaScript, images, or non-streamed media, must be less than 10 MB. The 10-MB limit applies to the encoded size of images. There is also a limit to the decoded size of images. See “Optimize Images.”
JavaScript execution is limited to 5 seconds for each top-level entry point. If your script executes longer than 5 seconds, Safari stops executing the script. This timeout ensures that JavaScript execution does not prevent the user from interacting with your page or navigating elsewhere.
Make sure that the JavaScript you download is exactly what you need for the current page. Unneeded JavaScript consumes precious memory resources. Websites that have been in existence for some time often contain unused JavaScript; a quick audit of your site can help you free up memory resources and improve site performance.
Supported Rich Media MIME Types
See "Safari Web Content Guide for iPhone" for supported rich media MIME types.
PDF Documents
PDF documents are easy to view on iPhone and even easier to page through. PDF documents linked to from web content are opened automatically. The page indicator keeps track of where users are in a document. And just like movies, users can rotate iPhone to view a PDF in landscape orientation.
Unsupported Technologies
You’ll want to avoid using Flash and Java for iPhone content. You’ll also want to avoid encouraging users to download the latest Flash to their iPhone, because neither Flash nor file downloads are supported by Safari on iPhone.
Differences Between Safari on iPhone and Safari on the Computer Desktop
There are a few differences between how Safari works on iPhone and on the computer desktop.
By default, Safari on iPhone blocks pop-up windows. However, it is a preference that users may change.
Safari on iPhone supports:
- Cookies
- User-initiated window-open calls. There is a limit of 8 pages (equivalent to 8 open windows) in page view.
Safari on iPhone does not support:
window.showModalDialog() or window.print()- Mouse-over events
- Hover styles
- Tool tips
- Java applets
- Flash
- SVG
- XSLT
- Plug-in installation
- Custom x.509 certificates
- WML
- File uploads and downloads
Security
Safari on iPhone uses essentially the same SSL implementation that it uses on the computer desktop to provide end-to-end security. The same encryption that prevents listening on the wire is just as secure when used in a wireless situation, whether through Wi-Fi or EDGE.
iPhone supports SSL 2, SSL 3, and TLS with many popular Cipher Suites.
RSA keys up to 4096 bits are supported.
HTTPS
Diffie-Hellman protocol and DSA keys and self-signed certificates are not available on iPhone.
Debugging
Use the Debug Console to debug web content on iPhone. Enable the console by navigating to Settings > Safari > Developer and sliding Debug Console to ON.The console displays errors, warnings, and tips generated by your webpages.