{ "metadata": { "source": "Apple Human Interface Guidelines", "source_url": "https://developer.apple.com/design/human-interface-guidelines/", "generated_at": "2026-03-24T10:09:01.952605+00:00", "article_count": 134, "format_version": "1.0", "purpose": "Agent-readable reference for designing Swift/SwiftUI applications following Apple HIG", "category": "technologies" }, "name": "Technologies", "articles": [ { "title": "AirPlay", "url": "https://developer.apple.com/design/human-interface-guidelines/airplay", "category": "technologies", "summary": "", "sections": [ { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Prefer the system-provided media player. The built-in media player offers a standard set of controls and supports features like chapter navigation, subtitles, closed captioning, and AirPlay streaming. It’s also easy to implement, provides a consistent and familiar playback experience across the system, and accommodates the needs of most media apps. Consider designing a custom video player only if the system-provided player doesn’t meet your app’s needs. For developer guidance, see AVPlayerViewController." }, { "type": "paragraph", "text": "Provide content in the highest possible resolution. Your HTTP Live Streaming (HLS) playlist needs to include the full range of available resolutions so that people can experience your content in the resolution that’s appropriate for the device they’re using (AVFoundation automatically selects the resolution based on the device). If you don’t include a range of resolutions, your content looks low quality when people stream it to a device that can play at higher resolutions. For example, content that looks great on iPhone at 720p will look low quality when people use AirPlay to stream it to a 4K TV." }, { "type": "paragraph", "text": "Stream only the content people expect. Avoid streaming content like background loops and short video experiences that make sense only within the context of the app itself. For developer guidance, see usesExternalPlaybackWhileExternalScreenIsActive." }, { "type": "paragraph", "text": "Support both AirPlay streaming and mirroring. Supporting both features gives people the most flexibility." }, { "type": "paragraph", "text": "Support remote control events. When you do, people can choose actions like play, pause, and fast forward on the lock screen, and through interaction with Siri or HomePod. For developer guidance, see Remote command center events." }, { "type": "paragraph", "text": "Don’t stop playback when your app enters the background or when the device locks. For example, people expect the TV show they started streaming from your app to continue while they check their mail or put their device to sleep. In this type of scenario, it’s also crucial to avoid automatic mirroring because people don’t want to stream other content on their device without explicitly choosing to do so." }, { "type": "paragraph", "text": "Don’t interrupt another app’s playback unless your app is starting to play immersive content. For example, if your app plays a video when it launches or auto-plays inline videos, play this content on only the local device, while allowing current playback to continue. For developer guidance, see ambient." }, { "type": "paragraph", "text": "Let people use other parts of your app during playback. When AirPlay is active, your app needs to remain functional. If people navigate away from the playback screen, make sure other in-app videos don’t begin playing and interrupt the streaming content." }, { "type": "paragraph", "text": "If necessary, provide a custom interface for controlling media playback. If you can’t use the system-provided media player, you can create a custom media player that gives people an intuitive way to enter AirPlay. If you need to do this, be sure to provide custom buttons that match the appearance and behavior of the system-provided ones, including distinct visual states that indicate when playback starts, is occurring, or is unavailable. Use only Apple-provided symbols in custom controls that initiate AirPlay, and position the AirPlay icon correctly in your custom player — that is, in the lower-right corner (in iOS 16 and iPadOS 16 and later)." } ] }, { "heading": "Using AirPlay icons", "level": 2, "content": [ { "type": "paragraph", "text": "You can download AirPlay icons in Resources. You have the following options for displaying the AirPlay icon in your app." } ] }, { "heading": "Black AirPlay icon", "level": 3, "content": [ { "type": "paragraph", "text": "Use the black AirPlay icon on white or light backgrounds when other technology icons also appear in black." } ] }, { "heading": "White AirPlay icon", "level": 3, "content": [ { "type": "paragraph", "text": "Use the white AirPlay icon on black or dark backgrounds when other technology icons also appear in white." } ] }, { "heading": "Custom color AirPlay icon", "level": 3, "content": [ { "type": "paragraph", "text": "Use a custom color when other technology icons also appear in the same color." }, { "type": "paragraph", "text": "Position the AirPlay icon consistently with other technology icons. If you display other technology icons within shapes, you can display the AirPlay icon in the same manner." }, { "type": "paragraph", "text": "Don’t use the AirPlay icon or name in custom buttons or interactive elements. Use the icon and the name AirPlay only in noninteractive ways." }, { "type": "paragraph", "text": "Pair the icon with the name AirPlay correctly. You can show the name below or beside the icon if you also reference other technologies in this way. Use the same font you use in the rest of your layout. Avoid using the AirPlay icon within text or as a replacement for the name AirPlay." }, { "type": "paragraph", "text": "Emphasize your app over AirPlay. Make references to AirPlay less prominent than your app name or main identity." } ] }, { "heading": "Referring to AirPlay", "level": 2, "content": [ { "type": "paragraph", "text": "Use correct capitalization when using the term AirPlay. AirPlay is one word, with an uppercase A and uppercase P, each followed by lowercase letters. If your layout displays only all-uppercase designations, you can typeset AirPlay in all uppercase to match the style of the rest of the layout." }, { "type": "paragraph", "text": "Always use AirPlay as a noun." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Use AirPlay to listen on your speaker" ], [ "", "AirPlay to your speaker" ], [ "", "You can AirPlay with [App Name]" ] ] }, { "type": "paragraph", "text": "Use terms like works with, use, supports, and compatible." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "[App Name] is compatible with AirPlay" ], [ "", "AirPlay-enabled speaker" ], [ "", "You can use AirPlay with [App Name]" ], [ "", "[App Name] has AirPlay" ] ] }, { "type": "paragraph", "text": "Use the name Apple with the name AirPlay if desired." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Compatible with Apple AirPlay" ] ] }, { "type": "paragraph", "text": "Refer to AirPlay if appropriate and to add clarity. If your content is specific to AirPlay, you can use Airplay to make that clear. You can also refer to AirPlay in technical specifications." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "[App Name] now supports AirPlay" ] ] } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS. Not supported in watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Design Resources" }, { "type": "paragraph", "text": "Apple Trademark List" }, { "type": "paragraph", "text": "Guidelines for Using Apple Trademarks and Copyrights" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "AVFoundation" }, { "type": "paragraph", "text": "AVKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/airplay#Best-practices" }, { "title": "Using AirPlay icons", "url": "/design/human-interface-guidelines/airplay#Using-AirPlay-icons" }, { "title": "Black AirPlay icon", "url": "/design/human-interface-guidelines/airplay#Black-AirPlay-icon" }, { "title": "White AirPlay icon", "url": "/design/human-interface-guidelines/airplay#White-AirPlay-icon" }, { "title": "Custom color AirPlay icon", "url": "/design/human-interface-guidelines/airplay#Custom-color-AirPlay-icon" }, { "title": "Referring to AirPlay", "url": "/design/human-interface-guidelines/airplay#Referring-to-AirPlay" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/airplay#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/airplay#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/airplay#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/airplay#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/airplay#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/airplay#Change-log" } ], "image_count": 0 }, { "title": "Always On", "url": "https://developer.apple.com/design/human-interface-guidelines/always-on", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "In the Always On state, a device can continue to give people useful, glanceable information in a low-power, privacy-preserving way by dimming the display and minimizing onscreen motion. The system can display different items depending on the device." }, { "type": "list", "items": [ "On iPhone 14 Pro and iPhone 14 Pro Max, the system displays Lock Screen items like Widgets and Live Activities when people set aside their device face up and stop interacting with it.", "When people drop their wrist while wearing Apple Watch, the system dims the watch face, continuing to display the interface of the app as long as it’s either frontmost or running a background session." ] }, { "type": "paragraph", "text": "On both devices, the system displays notifications while in Always On, and people can tap the display to exit Always On and resume interactions." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Hide sensitive information. It’s crucial to redact personal information that people wouldn’t want casual observers to view, like bank balances or health data. You also need to hide personal information that might be visible in a notification; for guidance, see Notifications." }, { "type": "paragraph", "text": "Keep other types of personal information glanceable when it makes sense. On Apple Watch, for example, people typically appreciate getting pace and heart rate updates while they’re working out; on iPhone, people appreciate getting a glanceable update on a flight arrival or a notification when a ride-sharing service arrives. If people don’t want any information to be visible, they can turn off Always On." }, { "type": "paragraph", "text": "Keep important content legible and dim nonessential content. You can increase dimming on secondary text, images, and color fills to give more prominence to the information that’s important to people. For example, a to-do list app might remove row backgrounds and dim each item’s additional details to highlight its title. Also, if you display rich images or large areas of color, consider removing the images and using dimmed colors." }, { "type": "paragraph", "text": "Maintain a consistent layout. Avoid making distracting interface changes when Always On begins or ends and throughout the Always On experience. For example, when Always On begins, prefer transitioning an interactive component to an unavailable appearance — don’t just remove it. Within the Always On context, aim to make infrequent, subtle updates to the interface. For example, a sports app might pause granular play-by-play updates while in Always On, only updating the score when it changes. Note that unnecessary changes during Always On can be especially distracting on iPhone, because people often put their device face up on a surface, making motion on the screen visible even when they’re not looking directly at it." }, { "type": "paragraph", "text": "Gracefully transition motion to a resting state; don’t stop it instantly. Smoothly finishing the current motion helps communicate the transition and avoids making people think that something went wrong." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS or watchOS. Not supported in iPadOS, macOS, tvOS, or visionOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Designing for watchOS" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Designing your app for the Always On state — watchOS apps" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 12, 2023", "Updated intro image artwork." ], [ "September 23, 2022", "Expanded guidance to cover the Always On display on iPhone 14 Pro and iPhone 14 Pro Max." ] ] } ] } ], "platforms": [], "related": [ { "title": "Widgets", "url": "/design/human-interface-guidelines/widgets" }, { "title": "Live Activities", "url": "/design/human-interface-guidelines/live-activities" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/always-on#Best-practices" }, { "title": "Notifications", "url": "/design/human-interface-guidelines/notifications" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/always-on#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/always-on#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/always-on#Related" }, { "title": "Designing for watchOS", "url": "/design/human-interface-guidelines/designing-for-watchos" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/always-on#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/always-on#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/always-on#Change-log" } ], "image_count": 0 }, { "title": "App Clips", "url": "https://developer.apple.com/design/human-interface-guidelines/app-clips", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "App Clips deliver an experience from your app or game without requiring people to download the full app from the App Store. App Clips focus on a fast solution to a task or contain a demo that showcases the full app or game, and they remain on the device for a limited amount of time while preserving people’s privacy." }, { "type": "paragraph", "text": "People discover and launch App Clips in a variety of situations and contexts. At a physical location, people launch an App Clip by scanning an App Clip Code, NFC tag, or a QR code. An App Clip Code tends to be the best way for people to discover and launch your App Clip because its distinct design is immediately recognizable, and people trust it to offer a fast, secure way to launch an App Clip." }, { "type": "paragraph", "text": "On their device, people launch an App Clip from location-based suggestions they permit in Siri Suggestions, the Maps app, Smart App Banners on websites, App Clip cards in Safari, and by tapping links others share with them in the Messages app. Starting with iOS 17, an app can include links and App Clip previews that people tap to launch another app’s App Clip." }, { "type": "paragraph", "text": "Consider creating an App Clip if your app provides an in-the-moment experience that helps people perform a task over a finite amount of time. For example:" }, { "type": "list", "items": [ "A rental bike could come with an App Clip Code that people tap or scan to launch an App Clip that lets them rent the bike.", "A coffee shop could offer an App Clip for fast advance orders that customers launch from a Smart App Banner or an App Clip card on the shop’s website. Customers could share a link to the website from the Messages app, which recipients then tap to launch the App Clip from within Messages.", "A food truck could create marketing material (for example, a poster to promote a seasonal dish) that includes an App Clip Code. People can scan the App Clip Code with the Camera app on their device and instantly launch the App Clip to order the seasonal dish.", "A restaurant could let diners pay for a meal by launching an App Clip from the Maps app or a suggestion from Siri Suggestions, or by holding their device close to an App Clip Code or NFC tag at their table.", "A museum could have visitors scan App Clip Codes or QR codes on labels next to displayed works to launch an App Clip that reveals augmented reality content or provides audio commentary." ] }, { "type": "paragraph", "text": "Consider creating an App Clip to let people experience your app or game before committing to a purchase or subscription. Focus on providing people with an opportunity to experience and understand your app or game. For example:" }, { "type": "list", "items": [ "A game might offer an App Clip that lets people play a demo version of the game, including a tutorial and the first level of the game.", "A fitness app might offer an App Clip with a free workout and a guided meditation.", "A text editor might allow people to create and save a document using the demo App Clip." ] }, { "type": "paragraph", "text": "For developer guidance, see App Clips." } ] }, { "heading": "Designing your App Clip", "level": 2, "content": [ { "type": "paragraph", "text": "Allow people to complete a task or a demo in your App Clip. Don’t require people to install the full app to experience the entire demo, to complete a task, or to finish a level in a game." }, { "type": "paragraph", "text": "Focus on essential features. Interactions with App Clips are quick and focused. Limit features to what’s necessary to accomplish the task at hand. Reserve advanced or complex features for the app. If you offer a demo version of your full app, focus on essential features that give people a good sense of your game or your app’s functionality." }, { "type": "paragraph", "text": "Don’t use App Clips solely for marketing purposes. App Clips need to provide real value and help people accomplish tasks. Don’t use them as a means to advertise services or products, and don’t display ads in your App Clip." }, { "type": "paragraph", "text": "Avoid using web views in your App Clip. App Clips use native components and frameworks to offer an app-quality experience. If only web components are available to you, offer a quick link to your website instead of an App Clip." }, { "type": "paragraph", "text": "Design a linear, easy-to-use, and focused user interface. App Clips don’t need tab bars, complex navigation, or settings. Keep the number of screens and entry forms to a minimum. Remove extraneous information and reduce complexity in the user interface wherever possible." }, { "type": "paragraph", "text": "On launch, show the most relevant part of your App Clip. Skip unnecessary steps and take people immediately to the part of the App Clip that best fits their context." }, { "type": "paragraph", "text": "Ensure people can use your App Clip immediately. App Clips need to include all required assets, omit splash screens, and never make people wait on launch." }, { "type": "paragraph", "text": "Ensure your App Clip is small. The smaller your App Clip, the faster it will launch on a person’s device. Keeping your App Clip small is especially important when bandwidth is limited. As much as possible, reduce unnecessary code and remove unused assets. Avoid downloading additional data, which can take away the feeling of immediacy." }, { "type": "paragraph", "text": "Make the App Clip shareable. When someone shares a link to an App Clip in the Messages app, recipients can launch the App Clip from within the Messages app. Offer the ability to share links to specific points in your App Clip, and encourage people to share the App Clip with others." }, { "type": "paragraph", "text": "Make it easy to pay for a service or product. Entering payment information can be a long and error-prone task. Consider supporting Apple Pay to offer express checkout and let people enter shipping information with no typing." }, { "type": "paragraph", "text": "Avoid requiring people to create an account before they can benefit from your App Clip. Creating an account is a complex task that takes time and effort. Consider not requiring an account, or think about asking people to create an account after they finish a task. If your App Clip requires an account to provide value, limit the amount of information people need to provide — for example, by offering Sign in with Apple." }, { "type": "paragraph", "text": "Provide a familiar, focused experience in your app. When people install the full app, it replaces the App Clip on their device. From this moment, invocations that would have launched the App Clip launch the full app instead. Ensure your app provides a focused, familiar experience to people who previously used the App Clip. Don’t require additional steps that slow people down; for example, don’t require people to log in again when they transition from the App Clip to the app." } ] }, { "heading": "Preserving privacy", "level": 3, "content": [ { "type": "paragraph", "text": "The system imposes limits on App Clips to ensure people’s privacy. For example, App Clips can’t perform background operations. For developer guidance, see Choosing the right functionality for your App Clip." }, { "type": "paragraph", "text": "Limit the amount of data you store and handle yourself. If you need to store people’s data — for example, login information — store it securely. In addition, don’t rely on the availability of data you previously stored on the device — the system may have removed the App Clip from the device between launches and deleted all of its data. If you store login information, securely store it off the device." }, { "type": "paragraph", "text": "Consider offering Sign in with Apple. Sign in with Apple securely retains login information off people’s devices and preserves their privacy. For guidance, see Sign in with Apple." }, { "type": "paragraph", "text": "Offer a secure way to pay for services or goods that also respects people’s privacy. For example, consider offering Apple Pay." } ] }, { "heading": "Showcasing your app", "level": 3, "content": [ { "type": "paragraph", "text": "People don’t manage App Clips themselves, and App Clips don’t appear on the Home screen. Instead, the system removes an App Clip after a period of inactivity." }, { "type": "paragraph", "text": "Because apps remain the best way to keep people engaged over time, the system helps them discover and install the full app:" }, { "type": "list", "items": [ "On the App Clip card, people can either launch the App Clip or visit the full app’s page on the App Store.", "When people first launch the App Clip, the system displays an app banner at the top of the screen. Like the App Clip card, the banner allows people to visit the app’s page on the App Store." ] }, { "type": "paragraph", "text": "In addition, you can display an overlay in your App Clip that allows people to download the full app from within the App Clip." }, { "type": "paragraph", "text": "Don’t compromise the user experience by asking people to install the full app. If your App Clip offers an on-the-go experience, consider whether the App Clip card and the system-provided app banner provide enough incentive for people to download the full app. If your App Clip offers a demo experience, let people fully experience the demo before asking them to install the full app." }, { "type": "paragraph", "text": "Pick the right time to recommend your app. When someone completes a task or reaches a natural pause, display an SKOverlay that allows people to initiate a download of your full app or game from the context of the App Clip." }, { "type": "paragraph", "text": "Recommend your app in a nonintrusive, polite way. Don’t ask people to install the full app repeatedly or interrupt them during a task. Push notifications aren’t a good way to ask people to install the app either. Clearly communicate your app’s additional features." }, { "type": "paragraph", "text": "For developer guidance, see Recommending your app to App Clip users." } ] }, { "heading": "Limiting notifications", "level": 3, "content": [ { "type": "paragraph", "text": "App Clips provide the option to schedule and receive notifications for up to 8 hours after launch, enough time to follow up and complete most common tasks." }, { "type": "paragraph", "text": "Only ask for permission to use notifications for an extended period of time if it’s really needed. If your App Clip’s functionality spans more than a day, explicitly request permission to schedule and receive notifications. For example, a car rental company’s App Clip can ask for permission to send a notification that reminds people that they need to return a rented car soon." }, { "type": "paragraph", "text": "Keep notifications focused. Don’t send purely promotional notifications, and only use notifications in response to an explicit user action. If a person completes their task without leaving the App Clip, you might not need to send any notifications at all." }, { "type": "paragraph", "text": "Use notifications to help people complete a task. Notifications for an App Clip relate directly to the task the App Clip helps to accomplish. For example, an App Clip that helps people order food could send notifications related to a scheduled delivery." }, { "type": "paragraph", "text": "For developer guidance, see Enabling notifications in App Clips." } ] }, { "heading": "Creating App Clips for businesses", "level": 3, "content": [ { "type": "paragraph", "text": "If you’re a platform provider who services businesses, you may create several App Clip experiences in App Store Connect and use a single App Clip to power them all. To people using the App Clip, it appears with the branding of an individual business or location instead of your own branding." }, { "type": "paragraph", "text": "Use consistent branding. When people see the App Clip card for a business, the brand for that business is front and center. Tone down your own branding and make sure the branding for the business is clearly visible to avoid confusing people when they enter the App Clip experience." }, { "type": "paragraph", "text": "Consider multiple businesses. An App Clip may power many different businesses or a business that has multiple locations. In both scenarios, people may end up using the App Clip for more than one business or location at a time. The App Clip must handle this use case and update its user interface accordingly. For example, consider a way to switch between recent businesses or locations within your App Clip, and verify a person’s location when they launch it." }, { "type": "paragraph", "text": "For developer guidance, see Configuring App Clip experiences." } ] }, { "heading": "Creating content for an App Clip card", "level": 2, "content": [ { "type": "paragraph", "text": "The system-provided App Clip card is people’s first interaction with your App Clip, so give careful consideration to its images and copy." }, { "type": "paragraph", "text": "Be informative. Make sure the image on the App Clip card clearly communicates the features offered by your App Clip, supported tasks, or content." }, { "type": "paragraph", "text": "Prefer photography and graphics. Avoid using a screenshot of your app’s user interface because it’s unlikely to communicate the purpose of your App Clip. Instead, use an image that helps people understand the App Clip’s value, or a photo of the location of its associated business or point of interest." }, { "type": "paragraph", "text": "Avoid using text. Text in the header image isn’t localizable, can be difficult to read, and can make a card image less aesthetically pleasing." }, { "type": "paragraph", "text": "Adhere to image requirements. Use a 1800x1200 px PNG or JPEG image without transparency." }, { "type": "paragraph", "text": "Use concise copy. An App Clip card requires both a title and a subtitle. Clearly express the purpose of your App Clip within the available space so people can read and understand it at a glance. Create a title that has no more than 30 characters and a subtitle that has no more than 56 characters." }, { "type": "paragraph", "text": "Pick a verb for the action button that best fits your App Clip. Possible verbs are View, Play, or Open. Pick View for media, or if your App Clip provides informational or educational content. Pick Play for games. Choose Open for all other App Clips." } ] }, { "heading": "App Clip Codes", "level": 2, "content": [ { "type": "paragraph", "text": "App Clip Codes are the best way for people to discover your App Clip. Their distinct design is immediately recognizable, and they offer a fast, secure way to launch your App Clip." }, { "type": "paragraph", "text": "App Clip Code with the App Clip logo" }, { "type": "paragraph", "text": "App Clip Code without the App Clip logo" }, { "type": "paragraph", "text": "App Clip Codes always use the designs Apple provides and follow size, placement, and printing guidelines. Choose between the badge design that uses the App Clip logo ( App Clip) or, when space is at a premium, a design without it. Create App Clip Codes that use a default color pair, or choose custom foreground and background colors. For developer guidance, see Creating App Clip Codes." } ] }, { "heading": "Interacting with App Clip Codes", "level": 3, "content": [ { "type": "paragraph", "text": "App Clip Codes come in two variants: scan-only or with an embedded NFC tag (NFC-integrated)." }, { "type": "paragraph", "text": "The scan-only variant uses a camera icon in its center to let people know to use the Camera app or the Code Scanner in Control Center to scan the App Clip Code. The NFC-integrated variant uses an iPhone icon at its center that guides people to hold their device close to the App Clip Code or to scan it using the NFC Tag Reader in Control Center. People can also scan an NFC-integrated App Clip Code with the Camera app or the Code Scanner in Control Center. For example:" }, { "type": "list", "items": [ "A coffee shop could place an App Clip Code on their menu. A guest could hold their device close to the App Clip Code and instantly launch the shop’s App Clip to order a drink.", "A gas station could have an NFC-integrated App Clip Code attached to each pump. A traveler could hold their device close to it to launch the gas station’s App Clip and use it to pay for their refill.", "A video game creator could hand out marketing material at an industry event that includes an App Clip Code. An event attendee could scan the code to launch an App Clip that’s a playable demo of their latest video game." ] } ] }, { "heading": "Displaying App Clip Codes", "level": 3, "content": [ { "type": "paragraph", "text": "When you start designing your App Clip Codes, choose the variant that works best for the way people use your App Clip. If people can physically access the App Clip Code, use the NFC-integrated variant. For example:" }, { "type": "list", "items": [ "On a tabletop at a restaurant", "Near a register at a retail store", "In a storefront window", "On signage", "On a gift card or coupon" ] }, { "type": "paragraph", "text": "If you need to place your App Clip Code in an area that’s physically inaccessible or you need to display it digitally, use a scan-only App Clip Code. For example:" }, { "type": "list", "items": [ "On posters or printed advertising", "On signage behind a counter or unreachable in a storefront", "On digital materials such as digital displays, in emails, or on images you post to social media" ] }, { "type": "paragraph", "text": "No matter which of the two variants you use, it’s important you carefully consider where you place your App Clip Code to ensure a reliable scanning experience." }, { "type": "paragraph", "text": "Include the App Clip logo when space allows. The logo helps make it clear that the code launches an App Clip; however, if you can’t meet the clear space requirements, use the App Clip Code design without the App Clip logo. Also, use the design without the App Clip logo if you place the App Clip Code on disposable paper or plastic items, or on items associated with gambling or drinking. For example, use the App Clip Code without the App Clip logo on playing cards, poker chips, or bar coasters. The App Clip logo is always part of the badge design where it appears below the App Clip Code; never use the App Clip logo on its own." }, { "type": "paragraph", "text": "Place your App Clip Code on a flat or cylindrical surface only. If you place your App Clip Code on a cylindrical surface — for example, on a scooter’s handlebar — make sure the width of the App Clip Code doesn’t exceed one-sixth of the cylinder’s circumference." }, { "type": "paragraph", "text": "Help your App Clip Code remain as flat as possible so it’s easy for people to scan. To provide the best scanning experience, avoid displaying App Clip Codes on deformable materials that readily fold or crumple, such as paper, plastic, or fabric. If you need to make your App Clip Code available on a bag, flexible box, or other deformable object, display it on something rigid — like a card — that you attach to the object. If you create an App Clip Code sticker, make sure it adheres well to flat surfaces." }, { "type": "paragraph", "text": "Place your App Clip Code in a location that helps ensure reliable scanning. For example, place a scan-only App Clip Code in a location that offers enough light to ensure reliable scanning, and don’t require people to scan from a wide angle." }, { "type": "paragraph", "text": "Make sure the App Clip Code is unobstructed. Don’t overlay the App Clip Code with text, logos, or images. Never animate the App Clip Code or dim it." }, { "type": "paragraph", "text": "Display the App Clip Code in an upright position. Don’t rotate the generated App Clip Code or display the center glyph at an angle." }, { "type": "paragraph", "text": "Don’t create App Clip Codes that are too small. App Clip Codes must adhere to the following specifications." }, { "type": "table", "rows": [ [ "Type", "Minimum size" ], [ "Printed communications", "Minimum diameter of 3/4 inch (1.9 cm)." ], [ "Digital communications", "Minimum size of 256×256 px. Use a PNG or SVG file." ], [ "NFC-integrated App Clip Code", "The embedded NFC tag needs to be at least 35 mm in diameter or of equivalent size. For example, if your embedded NFC tag is 35 mm in diameter, your printed App Clip Code needs to be at least 1.37 inches (3.48 cm) in diameter." ] ] }, { "type": "paragraph", "text": "When determining the dimensions of your App Clip Codes, consider a distance to code size ratio of no more than 20:1. If possible, use a ratio of 10:1 to ensure reliable scanning. For example, an App Clip that people scan from 40 inches (101 cm) away needs to be at least 4 inches (10.16 cm) in diameter." }, { "type": "paragraph", "text": "If you display an App Clip Code near a QR Code or other scannable item, choose a size for the App Clip Code that’s at least the other code’s or item’s size." }, { "type": "paragraph", "text": "Provide enough space between an App Clip Code and adjacent App Clip Codes, graphics, or materials. The minimum clear space around an App Clip Code is equal to the space between the center glyph and the circular code. If you place your App Clip Code next to another App Clip Code or other machine-readable code, leave enough clear space to allow for reliable scanning of each code." } ] }, { "heading": "Using clear messaging", "level": 3, "content": [ { "type": "paragraph", "text": "Add clear messaging that informs people how they can use the App Clip Code to launch your App Clip, especially if you use the design without the App Clip logo. For example, add a call to action next to an App Clip Code you display in an email or on a poster. Use the suggested call-to-action messaging or your own copy. Always use a simple, clear call to action." }, { "type": "paragraph", "text": "For a scan-only App Clip Code, you can use the following call to action:" }, { "type": "list", "items": [ "Scan to [describe what people can do with your App Clip].", "Scan using the camera on your iPhone or iPad to [describe what people can do with your App Clip]." ] }, { "type": "paragraph", "text": "For an NFC-integrated App Clip Code, you can use the following call to action:" }, { "type": "list", "items": [ "Scan to [describe what people can do with your App Clip].", "Hold your iPhone near the [object name] to launch an App Clip that [describe what a person can do with your App Clip]." ] }, { "type": "paragraph", "text": "For more information, see NFC." }, { "type": "paragraph", "text": "Adhere to Guidelines for Using Apple Trademarks when referring to your App Clip and App Clip Codes. For example, Apple trademarks can’t appear in your app name or images, always use title case when using the terms App Clips or App Clip Code, and so on. For additional information, see Legal requirements." } ] }, { "heading": "Customizing your App Clip Code", "level": 3, "content": [ { "type": "paragraph", "text": "Use App Store Connect or the App Clip Code Generator command-line tool to create App Clip Codes, and follow best practices to ensure a reliable scanning experience." }, { "type": "paragraph", "text": "Always use the generated App Clip Code. Don’t create your own App Clip Code design or modify a generated App Clip Code in any way. Don’t apply filters, augment its colors, or add glows, shadows, gradients, or reflections. They negatively impact people’s scanning experience. When scaling a generated App Clip Code, don’t change the generated code’s aspect ratio, and be sure to scale all attributes of the App Clip Code — for example the stroke widths." }, { "type": "paragraph", "text": "Choose colors with enough contrast that ensure accurate scanning. Each App Clip Code uses three colors: a foreground color, a background color, and a third color that’s generated for you based on the foreground and background colors. Both App Store Connect and the App Clip Code Generator command-line tool offer a selection of default color pairs. Alternatively, you can choose custom foreground and background colors. Note that you can’t choose custom colors that will lead to a suboptimal scanning experience. If your color selection doesn’t work well, neither App Store Connect nor the command-line tool will generate an App Clip Code. To help you choose a color combination that works well, both tools contain functionality to suggest a different foreground color based on your custom background color. For more information, see Creating App Clip Codes with the App Clip Code Generator and Creating App Clip Codes with App Store Connect." } ] }, { "heading": "Printing guidelines", "level": 2, "content": [ { "type": "paragraph", "text": "App Clip Codes offer the best experience to launch App Clips. As a result, it’s important to manufacture and display App Clip Codes that offer a reliable scanning experience for a long time. You can print App Clip Codes yourself, or work with a professional printing service — for example, RR Donnelley." }, { "type": "paragraph", "text": "Always test printed App Clip Codes before you distribute them to be sure they’re scannable from a variety of angles." }, { "type": "paragraph", "text": "Use high-quality, non-textured print materials. Print App Clip Codes on matte finishes. Avoid shine, gloss, reflective or holographic overlays, as well as thin laminate finishes or materials. In case you need to laminate print material with an App Clip Code on it, use a matte laminate to avoid shine and reflections. If you place your App Clip Code outdoors, use UV-resistant materials or coatings to prevent fading from exposure to sunlight, rain, and other weather conditions. If you work with a professional printing service, use flexographic printing for best results. If you print the App Clip Codes yourself using a desktop printer, use an inkjet printer for best results." }, { "type": "paragraph", "text": "Use high-resolution images and printer settings. When rasterizing the SVG file, set the image resolution to at least 600 ppi, and print your App Clip Codes with a minimum resolution of 300 dpi. Consider leveling and calibrating your printer before printing to ensure a high print quality, and avoid poor color channel alignment, inaccurate gamma values, artifacts, or printing elliptical or otherwise distorted App Clip Codes. When using receipt printers, print App Clip Codes as close to the paper’s maximum bounds as possible." }, { "type": "paragraph", "text": "Use correct color settings when you convert the generated SVG file to a CMYK image. Both the App Clip Code Generator command-line tool and App Store Connect generate App Clip Codes as SVG files in the sRGB color space. To print colors that match the SVG file, convert the sRGB image to a CMYK image. Use a relative calorimetric (media-relative) intent when performing the conversion. Use “Generic CMYK ICC profile” on CMYK printers or “Gracol 2013 ICC profile” on CMYKOV printers and allow for a color tolerance CIELab Delta E of 2.5." }, { "type": "paragraph", "text": "If you’re using a printer that only prints in grayscale, only generate grayscale App Clip Codes. Codes generated in color and then printed in grayscale may work less reliably." }, { "type": "paragraph", "text": "For NFC-integrated App Clip Codes, choose Type 5 NFC tags. The embedded NFC tag needs to be at least 35 mm in diameter or of equivalent size." }, { "type": "paragraph", "text": "If you create large batches of App Clip Codes, thoroughly test your printing workflow, and verify printed App Clip Codes. For example, conduct small, inexpensive print runs using a subset of codes. Print your App Clip Codes on print templates with additional padded regions that allow you to display the encoded invocation URL and the SVG filename alongside each code for validation at the time of print." }, { "type": "paragraph", "text": "If you create many App Clip Codes with the App Clip Code Generator tool or App Store Connect, you’ll likely work with a professional printing service. If this is the case, you need to handle a lot of SVG files. Because you have no way of knowing which App Clip Code encodes which URL by looking at an App Clip Code, you need to use a file that contains information about which SVG file maps to which invocation URL. Under any circumstance, careful file management, versioning, and change tracking are key to avoiding faulty print runs. For more information, see Preparing multiple App Clip Codes for production." } ] }, { "heading": "Verifying your printer’s calibration", "level": 3, "content": [ { "type": "paragraph", "text": "A reliable scanning experience depends on the quality of your printed App Clip Codes. To ensure printing App Clip Codes results in a reliable scanning experience and to avoid using a printer that can’t print high-quality App Clip Codes, Apple offers printer calibration test sheets you can use to verify your printer’s settings and print quality." }, { "type": "paragraph", "text": "Verify print quality of your chosen color pair with the printer calibration test sheet that shows text boxes for each default color pair. Follow the instructions on the sheet to print it at the right scale and to verify that your printer can create high-quality App Clip Codes." }, { "type": "paragraph", "text": "Verify your printer’s grayscale settings by printing the printer calibration test sheet that shows two grayscale bars. If any of the specific gray colors are light or entirely missing, the printer may need calibration or may not be suitable for printing an App Clip Code that allows for reliable scanning." } ] }, { "heading": "Legal requirements", "level": 2, "content": [ { "type": "paragraph", "text": "Only the Apple-provided App Clip Codes created in App Store Connect or with the App Clip Code Generator command-line tool and that follow these guidelines are approved for use." }, { "type": "paragraph", "text": "App Clip Codes are approved for use to indicate availability of an App Clip. Apple may update the App Clip Code design from time to time at Apple’s discretion." }, { "type": "paragraph", "text": "In the event your App Clip is no longer active, also stop displaying the App Clip Code associated with that inactive App Clip." }, { "type": "paragraph", "text": "You may not use the App Clip Code (including, without limitation, the Apple Logo, the App Clip mark, and the App Clip Code designs) as part of your own company name or as part of your product name. You may not seek copyright or trademark registration for the App Clip Codes or any elements contained therein." }, { "type": "paragraph", "text": "The App Clip Codes described in these guidelines must not be used in any manner that is likely to reduce, diminish, or damage the goodwill, value, or reputation associated with Apple or App Clips; or that infringes or violates the trademarks or other proprietary rights of any third party; or that is likely to cause confusion as to the source of products or services." }, { "type": "paragraph", "text": "Apple retains all rights to its trademarks, copyrights, or other intellectual property rights contained in the materials provided for use hereunder, including, without limitation, the App Clip Codes and any elements contained therein." }, { "type": "paragraph", "text": "Don’t add a symbol to App Clip Codes created in App Store Connect or with the App Clip Code Generator command-line tool." }, { "type": "paragraph", "text": "Don’t translate any Apple trademark. Apple trademarks must remain in English even when they appear within text in a language other than English. With Apple’s approval, a translation of the legal notice and credit lines (but not the trademarks) can be used in materials distributed outside the U.S." }, { "type": "paragraph", "text": "For more information about using Apple trademarks, see Guidelines for Using Apple Trademarks." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Pay" }, { "type": "paragraph", "text": "Sign in with Apple" }, { "type": "paragraph", "text": "Guidelines for Using Apple Trademarks and Copyrights" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "App Clips" }, { "type": "paragraph", "text": "App Store Connect" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Updated guidance to include demo App Clips." ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Designing your App Clip", "url": "/design/human-interface-guidelines/app-clips#Designing-your-App-Clip" }, { "title": "Apple Pay", "url": "/design/human-interface-guidelines/apple-pay" }, { "title": "Sign in with Apple", "url": "/design/human-interface-guidelines/sign-in-with-apple" }, { "title": "Preserving privacy", "url": "/design/human-interface-guidelines/app-clips#Preserving-privacy" }, { "title": "Showcasing your app", "url": "/design/human-interface-guidelines/app-clips#Showcasing-your-app" }, { "title": "Limiting notifications", "url": "/design/human-interface-guidelines/app-clips#Limiting-notifications" }, { "title": "Creating App Clips for businesses", "url": "/design/human-interface-guidelines/app-clips#Creating-App-Clips-for-businesses" }, { "title": "Creating content for an App Clip card", "url": "/design/human-interface-guidelines/app-clips#Creating-content-for-an-App-Clip-card" }, { "title": "App Clip Codes", "url": "/design/human-interface-guidelines/app-clips#App-Clip-Codes" }, { "title": "Interacting with App Clip Codes", "url": "/design/human-interface-guidelines/app-clips#Interacting-with-App-Clip-Codes" }, { "title": "Displaying App Clip Codes", "url": "/design/human-interface-guidelines/app-clips#Displaying-App-Clip-Codes" }, { "title": "Using clear messaging", "url": "/design/human-interface-guidelines/app-clips#Using-clear-messaging" }, { "title": "NFC", "url": "/design/human-interface-guidelines/nfc" }, { "title": "Legal requirements", "url": "/design/human-interface-guidelines/app-clips#Legal-requirements" }, { "title": "Customizing your App Clip Code", "url": "/design/human-interface-guidelines/app-clips#Customizing-your-App-Clip-Code" }, { "title": "Printing guidelines", "url": "/design/human-interface-guidelines/app-clips#Printing-guidelines" }, { "title": "Verifying your printer’s calibration", "url": "/design/human-interface-guidelines/app-clips#Verifying-your-printers-calibration" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/app-clips#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/app-clips#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/app-clips#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/app-clips#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/app-clips#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/app-clips#Change-log" } ], "image_count": 0 }, { "title": "Apple Pay", "url": "https://developer.apple.com/design/human-interface-guidelines/apple-pay", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "People authorize payments and provide shipping and contact information, using credentials that are securely stored on the device." }, { "type": "tip", "text": "TipIt’s important to understand the difference between Apple Pay and In-app purchase. Use Apple Pay in your app to sell physical goods like groceries, clothing, and appliances; for services such as club memberships, hotel reservations, and tickets for events; and for donations. Use In-App Purchase in your app to sell virtual goods, such as premium content for your app, and subscriptions for digital content." }, { "type": "paragraph", "text": "Apps and websites that accept Apple Pay display it as an available payment option, and include an Apple Pay button in the purchasing flow that people tap to bring up a payment sheet. During checkout, the payment sheet can show the credit or debit card linked to Apple Pay, purchase amount (including tax and fees), shipping options, and contact information. People make any necessary adjustments and then authorize payment and complete the purchase. For developer guidance, see Apple Pay." }, { "type": "paragraph", "text": "All websites that offer Apple Pay must include a privacy statement and adhere to the Acceptable use guidelines for Apple Pay on the web. For developer guidance, see Apple Pay on the Web. For a hands-on demo of Apple Pay on the web, see Apple Pay on the web interactive demo." }, { "type": "paragraph", "text": "The device performs payment authentication in most cases where the device supports Face ID, Touch ID, or Optic ID. In some cases, the system transfers payment authentication to a nearby iPhone, iPad, or Apple Watch via a secure Bluetooth connection or a scannable code." } ] }, { "heading": "Offering Apple Pay", "level": 2, "content": [ { "type": "paragraph", "text": "Offer Apple Pay on all devices and browsers that support it. If the device doesn’t support Apple Pay, don’t present Apple Pay as a payment option. Use Apple Pay APIs to evaluate when a device can support Apple Pay. For developer guidance, see PKPaymentAuthorizationController (iOS, watchOS) and canMakePayments (web)." }, { "type": "paragraph", "text": "If you use Apple Pay APIs to find out whether someone has an active card in Wallet, you must make Apple Pay the primary — but not necessarily sole — payment option everywhere you use the APIs. For example, you might pre-select Apple Pay as the payment option when you display it alongside other options. For developer guidance, see Offering Apple Pay in Your App (iOS, watchOS) and Checking for Apple Pay availability (web)." }, { "type": "paragraph", "text": "If you also offer other payment methods, offer Apple Pay at the same time. Feature Apple Pay at least as prominently as the other options on every page or screen that offers or accepts payment methods." }, { "type": "paragraph", "text": "If you use an Apple Pay button to start the Apple Pay payment process, you must use the Apple-provided API to display it. Unlike a button graphic, the buttons produced by the API always have the correct appearance and are localized automatically." }, { "type": "paragraph", "text": "If you use a custom button to start the Apple Pay payment process, make sure your custom button doesn’t display “Apple Pay” or the Apple Pay logo. In this scenario, you must let people know that you accept Apple Pay by displaying the Apple Pay mark or referencing Apple Pay in text on the same page that displays your payment button." }, { "type": "paragraph", "text": "Use Apple Pay buttons only to start the Apple Pay payment process and, when appropriate, the Apple Pay set-up process. When people choose an Apple Pay button to make a purchase, but their device doesn’t have Apple Pay set up, they’re given the opportunity to set up Apple Pay. Don’t use Apple Pay buttons in any other ways." }, { "type": "paragraph", "text": "Don’t hide an Apple Pay button or make it appear unavailable. If an Apple Pay button can’t be used yet, such as when a product size or color hasn’t been selected, gracefully point out the problem after someone taps or clicks the button." }, { "type": "paragraph", "text": "Use the Apple Pay mark only to communicate that Apple Pay is accepted. The Apple Pay mark doesn’t facilitate payment. Never use it as a payment button or position it as a button. When using the Apple Pay mark to indicate Apple Pay as the selected payment method, you can create a separate custom button conforming to your app’s design to initiate the Apple Pay payment." }, { "type": "paragraph", "text": "Inform search engines that Apple Pay is accepted on your website. If your website uses semantic markup to provide product details to search engines, list Apple Pay as a payment option." }, { "type": "paragraph", "text": "For app developer guidance, see Apple Pay. For website developer guidance, including how to determine whether Apple Pay on the web is available, see Apple Pay on the Web." } ] }, { "heading": "Streamlining checkout", "level": 2, "content": [ { "type": "paragraph", "text": "Provide a cohesive checkout experience. It’s best when the entire checkout flow feels tightly integrated with your app or website. To strengthen people’s perception of integration, use your branding throughout the checkout experience and avoid opening different pages or windows. For website checkout flows in particular, opening new windows during the process can cause confusion and may even lead people to think they’ve been handed off to a different website." }, { "type": "paragraph", "text": "If Apple Pay is available, assume the person wants to use it. Consider presenting the Apple Pay button as the first payment option, displaying it larger than other options, or using a line to visually separate it from other choices." }, { "type": "paragraph", "text": "Accelerate single-item purchases with Apple Pay buttons on product detail pages. In addition to offering a shopping cart, consider putting Apple Pay buttons on product detail pages so people can purchase an individual item quickly. Purchases initiated in this way need to be for an individual item only, excluding any items that already reside in the shopping cart. If the shopping cart contains an item purchased directly from a product detail page, remove the item from the cart after the purchase is complete." }, { "type": "paragraph", "text": "Accelerate multi-item purchases with express checkout. Consider providing an express checkout feature that immediately displays the payment sheet, allowing people to purchase multiple items quickly using a single shipping method and destination. If you offer a coupon or promotional code, you can enhance the express checkout experience by letting people enter it on the payment sheet." }, { "type": "paragraph", "text": "Collect necessary information, like color and size options, before people reach the Apple Pay button. When additional information is needed at checkout time — perhaps because the customer forgot to choose an option — gracefully point out the problem and help them correct it. Use highlighting or warning text to identify missing information, and automatically navigate to the problematic field so people can correct it quickly and complete their purchase." }, { "type": "paragraph", "text": "Collect optional information before checkout begins. There’s no way to input optional data — like gift messages or delivery instructions — on the payment sheet, so collect this information ahead of time or even after the purchase is complete." }, { "type": "paragraph", "text": "Gather multiple shipping methods and destinations before showing the payment sheet. The payment sheet lets people select a single shipping method and destination for an entire order. If your customers can choose different shipping methods and destinations for individual items in an order, collect those details before Apple Pay checkout begins, instead of on the payment sheet." }, { "type": "paragraph", "text": "For in-store pickup, help people choose a pickup location before displaying the payment sheet. After a customer chooses the pickup location they want, use the read-only format to display the location’s address on the payment sheet. For developer guidance, see Displaying a Read-Only Pickup Address." }, { "type": "paragraph", "text": "Prefer information from Apple Pay. Assume that Apple Pay information is complete and up to date. Even if your app or website has existing contact, shipping, and payment information, consider fetching the latest from Apple Pay during checkout to reduce potential corrections." }, { "type": "paragraph", "text": "Avoid requiring account creation prior to purchase. If you want people to register for an account, ask them to do so on the order confirmation page. Prepopulate as many registration fields as possible using information provided by the payment sheet during checkout." }, { "type": "paragraph", "text": "Report the result of the transaction so that people can view it in the payment sheet. In failure cases, the payment sheet can display the errors that you provide, so people can take steps to fix the problem." }, { "type": "paragraph", "text": "Display an order confirmation or thank-you page. After the payment sheet shows the result of the transaction, display an order confirmation page to thank people for their purchase, provide details about when the order will ship, and indicate how to check its status. Listing Apple Pay on the confirmation page isn’t necessary, but if you do, show it after the last four digits of the account used to process the transaction or as a separate note. For example, ”1234 (Apple Pay)” or ”Paid with Apple Pay.”" } ] }, { "heading": "Customizing the payment sheet", "level": 3, "content": [ { "type": "paragraph", "text": "Only present and request essential information. People may get confused or have privacy concerns if the payment sheet includes extraneous information. For example, it makes sense to see a contact email address but not a shipping address if the purchase is a gift card that will be delivered electronically. Showing or asking for a shipping address in this scenario may give the false impression that something will be physically delivered." }, { "type": "paragraph", "text": "Display the active coupon or promotional code, or give people a way to enter it. For example, if people can enter a code before the payment sheet appears, displaying it on the sheet can reassure them that the code works as they expect. Alternatively, allowing code entry on the payment sheet can be particularly beneficial in an express checkout flow." }, { "type": "paragraph", "text": "Let people choose the shipping method in the payment sheet. To the extent space permits, show a clear description, a cost, and, optionally, an estimated delivery or pickup date — or range of dates — for each available option. In iOS 15 and later, you can take advantage of the shipping method’s calendar and time-zone support to provide accurate delivery or pickup information, regardless of the customer’s current location. For developer guidance, see PKDateComponentsRange." }, { "type": "paragraph", "text": "For in-store pickup, consider letting people choose a pickup window that works for them. You can use the shipping method to supply a range of dates and times from which people can choose." }, { "type": "paragraph", "text": "Use line items to explain additional charges, discounts, pending costs, add-on donations, recurring, and future payments. A line item includes a label and cost; a line item for a recurring payment can also include a frequency. Don’t use line items to show an itemized list of products that make up the purchase. For developer guidance, see paymentSummaryItems; for guidance on donations, see Supporting donations." }, { "type": "paragraph", "text": "Keep line items short. Make line items specific and easily understandable at a glance. Whenever possible, fit line items on a single line." }, { "type": "paragraph", "text": "Provide a business name after the word Pay on the same line as the total. Use the same business name people will see when they look for the charge on their bank or credit card statement. This provides reassurance that payment is going to the right place. For example, Pay [Business_Name]." }, { "type": "paragraph", "text": "If you’re not the end merchant, specify both your business name and the end merchant’s name in the payment sheet. There are a few ways your app, App Clip, or website might help people make a purchase from an end merchant that’s unrelated to your company. For example, a marketplace app can help people make a purchase from an end merchant they might not recognize. Another example is an app that offers a self-checkout service people can use to pay for an item in an end merchant’s physical store without visiting the store’s checkout counter. In scenarios like these, people might not realize two businesses are involved in the transaction, so it’s essential to name both businesses and clarify their roles. When your app acts as an intermediary for an end merchant, clearly and succinctly describe the situation in the Pay line of the payment sheet, using something like Pay [End_Merchant_Business_Name (via Your_Business_Name)]." }, { "type": "paragraph", "text": "Clearly disclose when additional costs may be incurred after payment authorization. In some cases, the total cost may be unknown at checkout time. For example, the price of a car ride based on distance or time might change after checkout. Or, a customer might want to add a tip after a product is delivered. In situations like these, and when local regulations allow, you can provide a clear explanation in the payment sheet and a subtotal marked as Amount Pending. If you’re preauthorizing a specific amount, be sure the payment sheet accurately reflects this information." }, { "type": "paragraph", "text": "Handle data entry and payment errors gracefully. If an error occurs during checkout, help people resolve it quickly so they can complete their transaction. For related guidance, see Data validation." } ] }, { "heading": "Displaying a website icon", "level": 3, "content": [ { "type": "paragraph", "text": "Many websites provide an icon that can display with bookmarks, in URL fields, or on a device’s Home screen. Websites that support Apple Pay can display this icon in a summary view and in the payment sheet of the connected device that’s used to authorize payment. The icon provides visual reassurance that payment is going to the right place." }, { "type": "paragraph", "text": "If your website supports Apple Pay, provide an icon in the following sizes for use in the summary view and the payment sheet:" }, { "type": "table", "rows": [ [ "@2x", "@3x" ], [ "60x60 pt (120x120 px @2x)", "60x60 pt (180x180 px @3x)" ] ] } ] }, { "heading": "Handling errors", "level": 2, "content": [ { "type": "paragraph", "text": "Provide clear, actionable guidance when problems occur during checkout or payment processing, so people can resolve problems quickly and complete their transaction." } ] }, { "heading": "Data validation", "level": 3, "content": [ { "type": "paragraph", "text": "Your app or website can respond to user input when the payment sheet appears, when people change certain field values on the payment sheet, and after they authenticate the transaction. Use these opportunities to check for data entry problems and to provide clear and consistent messaging." }, { "type": "paragraph", "text": "Payment sheet error messaging" }, { "type": "paragraph", "text": "Custom detail view error messaging" }, { "type": "paragraph", "text": "Payment sheet error messaging" }, { "type": "paragraph", "text": "Custom detail view error messaging" }, { "type": "paragraph", "text": "When data is invalid, system-provided error messaging calls attention to relevant fields on the payment sheet. People can choose a field to view additional details and resolve the problem. Provide customized error messages for the detail view that appears when people choose a problematic field." }, { "type": "paragraph", "text": "For developer guidance, see PKPaymentAuthorizationViewControllerDelegate (iOS, watchOS) and Apple Pay on the Web (web)." }, { "type": "note", "text": "NoteFor privacy reasons, your app or website has limited access to data until people attempt to authorize a transaction. Prior to authorization, only the card type and a redacted shipping address are accessible. It’s critical to display errors when authorization fails, but to the extent possible, you also need to attempt to validate available information and report problems before authorization." }, { "type": "paragraph", "text": "Avoid forcing compliance with your business logic. Design a data validation process that’s intelligent enough to ignore irrelevant data and infer missing data whenever possible. For example, if your app requires a five-digit zip code but someone enters a Zip+4 code, ignore the additional digits rather than asking for a correction. Let people enter phone numbers in multiple formats — such as with and without dashes, and with and without a country code — without producing an error." }, { "type": "paragraph", "text": "Provide accurate status reporting to the system. When a problem occurs, it’s essential that your app or website accurately indicate the type of problem so the system can show the most relevant error message on the payment sheet. This is done by accompanying your custom error message with the correct status code. For developer guidance, see PKPaymentError (iOS, watchOS) and Apple Pay Status Codes (web)." }, { "type": "paragraph", "text": "Succinctly and specifically describe the problem when data is invalid or incorrectly formatted. Reference the relevant field and indicate exactly what’s expected. For example, if people enter an invalid zip code, instead of showing “Address is invalid,” show a specific message like “Zip code doesn’t match city.” If the shipping address is unserviceable, indicate why with a message like “Shipping not available for this state.” Use noun phrases with sentence-style capitalization and no ending punctuation. Aim to keep messages at 128 characters or fewer to avoid truncation." } ] }, { "heading": "Payment processing", "level": 3, "content": [ { "type": "paragraph", "text": "Handle interruptions correctly. A user-driven event like a cancellation or a system-driven event like a timeout could cause an interruption in the payment flow, resulting in the payment sheet being dismissed. When such an event occurs, you must cancel any in-progress payment. After the payment sheet dismisses, people can restart the process by choosing the Apple Pay button again. For developer guidance, see PKPaymentAuthorizationViewControllerDelegate (iOS, watchOS) and oncancel (web)." } ] }, { "heading": "Supporting subscriptions", "level": 2, "content": [ { "type": "paragraph", "text": "Your app or website can use Apple Pay to request authorization for recurring fees. A recurring fee can be a fixed amount, such as a monthly movie ticket subscription, or — when local regulations allow — a variable amount like a weekly grocery order. The initial authorization can also include discounts and additional fees." }, { "type": "paragraph", "text": "Fixed subscription" }, { "type": "paragraph", "text": "Variable subscription (where local regulations allow)" }, { "type": "paragraph", "text": "Fixed subscription" }, { "type": "paragraph", "text": "Variable subscription (where local regulations allow)" }, { "type": "paragraph", "text": "Clarify subscription details before showing the payment sheet. Before asking people to authorize a recurring payment, make sure they fully understand the billing frequency and any other terms of service. You can reiterate the billing frequency on the payment sheet." }, { "type": "paragraph", "text": "Include line items that reiterate billing frequency, discounts, and additional upfront fees. Use these line items to remind people what they’re authorizing. If no payment is required at authorization time, clearly disclose when billing will occur." }, { "type": "paragraph", "text": "No payment required at authorization" }, { "type": "paragraph", "text": "No payment required at authorization" }, { "type": "paragraph", "text": "Clarify the current payment amount in the total line. Make sure people know the amount they’re being billed at the time of authorization." }, { "type": "paragraph", "text": "Only show the payment sheet when a subscription change results in additional fees. When the someone changes a subscription, authorization isn’t necessary if the cost decreases or remains the same." } ] }, { "heading": "Supporting donations", "level": 3, "content": [ { "type": "paragraph", "text": "Approved nonprofits can use Apple Pay to accept donations." }, { "type": "paragraph", "text": "Use a line item to denote a donation. Display a line item on the payment sheet that reminds people they’re authorizing a donation; for example, display Donation $50.00." }, { "type": "paragraph", "text": "Streamline checkout by offering predefined donation amounts. You can reduce steps in the donation process by offering one-step recommended donations, like $25, $50, $100. Be sure to include an Other Amount option too, so people can customize the donation if they prefer." } ] }, { "heading": "Using Apple Pay buttons", "level": 2, "content": [ { "type": "paragraph", "text": "The system provides several Apple Pay button types and styles you can use in your app or website. In contrast to the Apple Pay buttons, you use the Apple Pay mark to communicate the availability of Apple Pay as a payment option." }, { "type": "paragraph", "text": "Don’t create your own Apple Pay button design or attempt to mimic the system-provided button designs." }, { "type": "paragraph", "text": "For developer guidance, see PKPaymentButtonType and PKPaymentButtonStyle (iOS and macOS), WKInterfacePaymentButton (watchOS), and Apple Pay on the Web (web)." } ] }, { "heading": "Button types", "level": 3, "content": [ { "type": "paragraph", "text": "Apple provides several types of buttons so you can choose the button type that fits best with the terminology and flow of your purchase or payment experience." }, { "type": "paragraph", "text": "Use the Apple-provided APIs to create Apple Pay buttons. When you use the system-provided APIs, you get:" }, { "type": "list", "items": [ "A button that is guaranteed to use an Apple-approved caption, font, color, and style", "Assurance that the button’s contents maintain ideal proportions as you change its size", "Automatic translation of the button’s caption into the language that’s set for the device", "Support for configuring the button’s corner radius to match the style of your UI", "A system-provided alternative text label that lets VoiceOver describe the button" ] }, { "type": "table", "rows": [ [ "Payment button type", "Example usage" ], [ "", "An area in an app or website where people can make a purchase, such as a product detail page or shopping cart page." ], [ "", "An app or website that lets people pay bills or invoices, such as those for a utility — like cable or electricity — or a service like plumbing or car repair." ], [ "", "An app or website offering a shopping cart or purchase experience that includes other payment buttons that start with the text Check out." ], [ "", "An app or website offering a shopping cart or purchase experience that includes other payment buttons that start with the text Continue with." ], [ "", "An app or website that helps people book flights, trips, or other experiences." ], [ "", "An app or website for an approved nonprofit that lets people make donations." ], [ "", "An app or website that lets people purchase a subscription, such as a gym membership or a meal-kit delivery service." ], [ "", "An app or website that uses the term reload to help people add money to a card, account, or payment system associated with a service, such as transit or a prepaid phone plan." ], [ "", "An app or website that uses the term add money to help people add money to a card, account, or payment system associated with a service, such as transit or a prepaid phone plan." ], [ "", "An app or website that uses the term top up to help people add money to a card, account, or payment system associated with a service, such as transit or a prepaid phone plan." ], [ "", "An app or website that lets people place orders for items like meals or flowers." ], [ "", "An app or website that lets people rent items like cars or scooters." ], [ "", "An app or website that uses the term support to help people give money to projects, causes, organizations, and other entities." ], [ "", "An app or website that uses the term contribute to help people give money to projects, causes, organizations, and other entities." ], [ "", "An app or website that lets people tip for goods or services." ], [ "", "An app or website that has stylistic reasons to use a button that can have a smaller minimum width or that doesn’t specify a call to action. If you choose a payment button type that isn’t supported on the version of the operating system your app or website is running in, the system may replace it with this button." ] ] }, { "type": "paragraph", "text": "When a device supports Apple Pay, but it hasn’t been set up yet, you can use the Set up Apple Pay button to show that Apple Pay is accepted and to give people an explicit opportunity to set it up." }, { "type": "paragraph", "text": "You can display the Set up Apple Pay button on pages such as a Settings page, a user profile screen, or an interstitial page. Tapping the button in any of these locations needs to initiate the process of adding a card." } ] }, { "heading": "Button styles", "level": 3, "content": [ { "type": "paragraph", "text": "You can use the automatic style to let the current system appearance determine the appearance of the Apple Pay buttons in your app (for developer guidance, see PKPaymentButtonStyle.automatic). If you want to control the button appearance yourself, you can use one of the following options. For web developer guidance, see ApplePayButtonStyle." } ] }, { "heading": "Black", "level": 4, "content": [ { "type": "paragraph", "text": "Use on white or light-color backgrounds that provide sufficient contrast. Don’t use on black or dark backgrounds." } ] }, { "heading": "White with outline", "level": 4, "content": [ { "type": "paragraph", "text": "Use on white or light-color backgrounds that don’t provide sufficient contrast. Don’t place on dark or saturated backgrounds." } ] }, { "heading": "White", "level": 4, "content": [ { "type": "paragraph", "text": "Use on dark-color backgrounds that provide sufficient contrast." } ] }, { "heading": "Button size and position", "level": 3, "content": [ { "type": "paragraph", "text": "Prominently display the Apple Pay button. Make the Apple Pay button no smaller than other payment buttons, and avoid making people scroll to see it." }, { "type": "paragraph", "text": "Position the Apple Pay button correctly in relation to an Add to Cart button. In a side-by-side layout, place the Apple Pay button to the right of an Add to Cart button." }, { "type": "paragraph", "text": "In a stacked layout, place the Apple Pay button above an Add to Cart button." }, { "type": "paragraph", "text": "Adjust the corner radius to match the appearance of other buttons. By default, an Apple Pay button has rounded corners. You can change the corner radius to produce a button with square corners or a capsule-shape button. For developer guidance, see cornerRadius." }, { "type": "paragraph", "text": "Minimum corner radius" }, { "type": "paragraph", "text": "Default corner radius" }, { "type": "paragraph", "text": "Maximum corner radius" }, { "type": "paragraph", "text": "Maintain the minimum button size and margins around the button. Be mindful that the button title may vary in length depending on the locale." }, { "type": "note", "text": "NoteIf the size you specify doesn’t accommodate the translated title for the type of payment button you’re using, the system automatically replaces it with the plain Apple Pay button shown below on the left. There is no automatic replacement for the Set up Apple Pay button." }, { "type": "paragraph", "text": "Use the following values for guidance." }, { "type": "table", "rows": [ [ "Button", "Minimum width", "Minimum height", "Minimum margins" ], [ "Apple Pay", "100pt (100px @1x, 200px @2x)", "30pt (30px @1x, 60px @2x)", "1/10 of the button’s height" ], [ "Book with Apple Pay", "140pt (140px @1x, 280px @2x)", "30pt (30px @1x, 60px @2x)", "1/10 of the button’s height" ], [ "Buy with Apple Pay" ], [ "Check out with Apple Pay" ], [ "Donate with Apple Pay" ], [ "Set up Apple Pay" ], [ "Subscribe with Apple Pay" ] ] } ] }, { "heading": "Apple Pay mark", "level": 3, "content": [ { "type": "paragraph", "text": "Use the Apple Pay mark graphic to show that Apple Pay is an available payment option when showing other payment options in a similar manner. The Apple Pay mark isn’t a button; if you need an Apple Pay button, choose one of the buttons described in Button types. For design guidance related to showing Apple Pay as a payment option, see Offering Apple Pay." }, { "type": "paragraph", "text": "Use only the artwork provided by Apple, with no alterations other than height. You can specify a height for the Apple Pay mark, but make sure that the height you use is equal to or larger than other payment brand marks in your payment flow. Don’t adjust the width, corner radius, or aspect ratio of the artwork; don’t add a trademark symbol or any other content; don’t remove the border; don’t add visual effects to the mark, such as shadows, glows, or reflections; and don’t flip, rotate, or animate the Apple Pay mark." }, { "type": "paragraph", "text": "Maintain a minimum clear space around the mark of 1/10 of its height. Don’t let the Apple Pay mark share its surrounding border with another graphic or button." }, { "type": "paragraph", "text": "Download the Apple Pay mark graphic and full usage guidelines here." } ] }, { "heading": "Referring to Apple Pay", "level": 2, "content": [ { "type": "paragraph", "text": "As with all Apple product names, use Apple Pay exactly as shown in Apple Trademark List — never make it plural or possessive — and adhere to Guidelines for Using Apple Trademarks." }, { "type": "paragraph", "text": "You can use plain text to promote Apple Pay and indicate that Apple Pay is a payment option." }, { "type": "paragraph", "text": "Capitalize Apple Pay in text as it appears in the Apple Trademark list. Use two words with an uppercase A, an uppercase P, and lowercase for all other letters. Display Apple Pay entirely in uppercase only when doing so is necessary for conforming to an established, typographic interface style, such as in an app that capitalizes all text." }, { "type": "paragraph", "text": "Never use the Apple logo to represent the name Apple in text. In the United States, use the registered trademark symbol (®) the first time Apple Pay appears in body text. Don’t include a registered trademark symbol when Apple Pay appears as a selection option during checkout." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Purchase with Apple Pay" ], [ "", "Purchase with Apple Pay®" ], [ "", "Purchase with ApplePay" ], [ "", "Purchase with  Pay" ], [ "", "Purchase with APPLE PAY" ] ] }, { "type": "paragraph", "text": "Coordinate the font face and size with your app. Don’t mimic Apple typography. Instead, use text attributes that are consistent with the rest of your app or website." }, { "type": "paragraph", "text": "Don’t translate Apple Pay or any other Apple trademark. Always use Apple trademarks in English, even when they appear within non-English text." }, { "type": "paragraph", "text": "In a payment selection context, you can display a text-only description of Apple Pay only when all payment options have text-only descriptions. If any other payment option description includes an icon or logo, you must use the Apple Pay mark as described in Offering Apple Pay." }, { "type": "paragraph", "text": "When promoting your app’s use of Apple Pay, follow App Store guidelines. Before promoting Apple Pay for your app, refer to the App Store marketing guidelines." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, visionOS, or watchOS. Not supported in tvOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Pay Marketing Guidelines" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Pay — PassKit" }, { "type": "paragraph", "text": "Apple Pay on the Web" }, { "type": "paragraph", "text": "WKInterfacePaymentButton — WatchKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 16, 2025", "Clarified supported platforms, including web browsers and Apple Vision Pro." ], [ "June 10, 2024", "Updated links to developer guidance for offering Apple Pay on the web." ], [ "September 12, 2023", "Updated artwork." ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "In-app purchase", "url": "/design/human-interface-guidelines/in-app-purchase" }, { "title": "Offering Apple Pay", "url": "/design/human-interface-guidelines/apple-pay#Offering-Apple-Pay" }, { "title": "Streamlining checkout", "url": "/design/human-interface-guidelines/apple-pay#Streamlining-checkout" }, { "title": "Customizing the payment sheet", "url": "/design/human-interface-guidelines/apple-pay#Customizing-the-payment-sheet" }, { "title": "Supporting donations", "url": "/design/human-interface-guidelines/apple-pay#Supporting-donations" }, { "title": "Data validation", "url": "/design/human-interface-guidelines/apple-pay#Data-validation" }, { "title": "Displaying a website icon", "url": "/design/human-interface-guidelines/apple-pay#Displaying-a-website-icon" }, { "title": "Handling errors", "url": "/design/human-interface-guidelines/apple-pay#Handling-errors" }, { "title": "Payment processing", "url": "/design/human-interface-guidelines/apple-pay#Payment-processing" }, { "title": "Supporting subscriptions", "url": "/design/human-interface-guidelines/apple-pay#Supporting-subscriptions" }, { "title": "Using Apple Pay buttons", "url": "/design/human-interface-guidelines/apple-pay#Using-Apple-Pay-buttons" }, { "title": "Apple Pay mark", "url": "/design/human-interface-guidelines/apple-pay#Apple-Pay-mark" }, { "title": "Button types", "url": "/design/human-interface-guidelines/apple-pay#Button-types" }, { "title": "Button styles", "url": "/design/human-interface-guidelines/apple-pay#Button-styles" }, { "title": "Black", "url": "/design/human-interface-guidelines/apple-pay#Black" }, { "title": "White with outline", "url": "/design/human-interface-guidelines/apple-pay#White-with-outline" }, { "title": "White", "url": "/design/human-interface-guidelines/apple-pay#White" }, { "title": "Button size and position", "url": "/design/human-interface-guidelines/apple-pay#Button-size-and-position" }, { "title": "Referring to Apple Pay", "url": "/design/human-interface-guidelines/apple-pay#Referring-to-Apple-Pay" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/apple-pay#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/apple-pay#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/apple-pay#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/apple-pay#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/apple-pay#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/apple-pay#Change-log" } ], "image_count": 0 }, { "title": "Augmented reality", "url": "https://developer.apple.com/design/human-interface-guidelines/augmented-reality", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Using the device’s camera to present the physical world onscreen live, your app can superimpose three-dimensional virtual objects, creating the illusion that these objects actually exist. Depending on the platform and the experiences your app offers, people can reorient the device to explore the objects from different angles, interact with objects using gestures and movement, and even join other people in multiuser AR experiences. For developer guidance, see ARKit." }, { "type": "paragraph", "text": "Offer AR features only on capable devices. If your app’s primary purpose is AR, make your app available only to devices that support ARKit. If your app includes features that require specific AR capabilities, or if AR features are optional in your app, don’t show people an error if they try to use these features on a device that doesn’t support them; instead, simply avoid offering the feature on an unsupported device. For developer guidance, see Verifying Device Support and User Permission." }, { "type": "note", "text": "NoteThe following guidance applies to apps that run in iOS and iPadOS. To learn about using ARKit to create immersive augmented reality experiences in visionOS, see ARKit." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Let people use the entire display. Devote as much of the screen as possible to displaying the physical world and your app’s virtual objects. Avoid cluttering the screen with controls and information that diminish the immersive experience." }, { "type": "paragraph", "text": "Strive for convincing illusions when placing realistic objects. Design detailed 3D assets with lifelike textures to create objects that appear to inhabit the physical environment in which you place them. Using information from ARKit, you can scale objects properly and position them on detected real-world surfaces, reflect environmental lighting conditions and simulate camera grain, cast top-down diffuse object shadows on real-world surfaces, and update visuals as the camera’s position changes. To help avoid breaking the illusion you create, make sure your app updates scenes 60 times per second so objects don’t appear to jump or flicker." }, { "type": "paragraph", "text": "Consider how virtual objects with reflective surfaces show the environment. Reflections in ARKit are approximations based on the environment captured by the camera. To help maintain the illusion that an AR experience is real, prefer small or coarse reflective surfaces that downplay the effect of these approximations." }, { "type": "paragraph", "text": "Use audio and haptics to enhance the immersive experience. A sound effect or bump sensation is a great way to confirm that a virtual object has made contact with a physical surface or other virtual object. Background music can also help envelop people in the virtual world. For guidance, see Playing audio and Playing haptics." }, { "type": "paragraph", "text": "Minimize text in the environment. Display only the information that people need for your app experience." }, { "type": "paragraph", "text": "If additional information or controls are necessary, consider displaying them in screen space. Content in screen space appears fixed to a consistent location either in the virtual world or, less commonly, on the device screen. It’s typically easy for people to find and view content in screen space because it remains stationary while the underlying AR environment moves with the device." }, { "type": "paragraph", "text": "Consider using indirect controls when you need to provide persistent controls. Indirect controls are not part of the virtual environment — instead, they are 2D controls displayed in screen space. If people need access to persistent controls in your app, consider placing the controls so that people don’t have to adjust how they’re holding the device to reach them. Also, consider using translucency in an indirect control to help avoid blocking the underlying scene. For example, the Measure app uses screen space to display a mix of translucent and opaque controls that people use to measure objects in the real world." }, { "type": "paragraph", "text": "Anticipate that people will use your app in a wide variety of real-world environments. People may open your app in a place where there isn’t much room to move around or there aren’t any large, flat surfaces. Clearly communicate your app’s requirements and expectations to people up front to help them understand how their physical environment can affect their AR experience. You might also consider offering different sets of features for use in different environments." }, { "type": "paragraph", "text": "Be mindful of people’s comfort. Holding a device at a certain distance or angle for a prolonged period can be fatiguing. To help avoid causing fatigue, consider placing objects at a distance that reduces the need to move the device closer to the object; in a game, consider keeping levels short and intermixed with brief periods of downtime." }, { "type": "paragraph", "text": "If your app encourages people to move, introduce motion gradually. For example, you might not want to make people dodge a virtual projectile as soon as they enter your AR game. Give people time to adapt to the AR experience in your app and then progressively encourage movement." }, { "type": "paragraph", "text": "Be mindful of people’s safety. When people are immersed in an AR experience, they’re not necessarily aware of their physical surroundings, so making rapid, sweeping, or expansive motions might be dangerous. Consider ways of making your app safe to operate; for example, a game could avoid encouraging large or sudden movements." } ] }, { "heading": "Providing coaching", "level": 2, "content": [ { "type": "paragraph", "text": "Before people can enjoy an AR experience in your app, they need to move their device in ways that lets ARKit evaluate the surroundings and detect surfaces. Consider using the built-in coaching view to show people what to do and provide feedback during the initialization process. You can also use the coaching view to help people reinitialize AR — a process known as relocalization — after an AR experience is interrupted by, for example, people switching briefly to a different app. For guidance on relocalization, see Handling interruptions; for developer guidance, see ARCoachingOverlayView." }, { "type": "paragraph", "text": "Hide unnecessary app UI while people are using a coaching view. By default, the coaching view appears automatically when initialization or relocalization starts, so be prepared to hide unrelated UI to help people concentrate on the coaching view’s instructions." }, { "type": "paragraph", "text": "If necessary, offer a custom coaching experience. Although you can configure the system-provided coaching view to help people provide specific information — such as the detection of a horizontal or vertical plane — you might need additional information or want to use a different visual style. If you want to design a custom coaching experience, use the system-provided coaching view for reference." } ] }, { "heading": "Helping people place objects", "level": 2, "content": [ { "type": "paragraph", "text": "Show people when to locate a surface and place an object. You can use the system-provided coaching view to help people find a horizontal or vertical flat surface on which to place an object. After ARKit detects a surface, your app can display a custom visual indicator to show when object placement is possible. You can help people understand how the placed object will look in the environment by aligning your indicator with the plane of the detected surface." }, { "type": "paragraph", "text": "App-specific indicator" }, { "type": "paragraph", "text": "When people place an object, immediately integrate that object into the AR environment. Although surface detection quickly and progressively refines accuracy, it’s best to avoid waiting for more accurate data before placing an object. Use the information available to respond instantly when people place an object; then, when surface detection completes, subtly refine the object’s position if necessary. For example, if people place an object beyond the bounds of the detected surface, gently nudge the object back onto the surface. For developer guidance on refining an object’s position, see ARTrackedRaycast." }, { "type": "paragraph", "text": "Consider guiding people toward offscreen virtual objects. Sometimes, it can be difficult for people to locate an object that’s positioned offscreen. When this is the case, you can help people find such objects by offering visual or audible cues. For example, if an object is offscreen to the left, you could display an indicator along the left edge of the screen that guides people to point the camera in that direction." }, { "type": "paragraph", "text": "Avoid trying to precisely align objects with the edges of detected surfaces. In AR, surface boundaries are approximations that may change as people’s surroundings are further analyzed." }, { "type": "paragraph", "text": "Incorporate plane classification information to inform object placement. For example, only let people place a virtual piece of furniture on a plane that’s classified as “floor,” or require a plane to be classified as “table” in order to place a virtual game board." } ] }, { "heading": "Designing object interactions", "level": 2, "content": [ { "type": "paragraph", "text": "Let people use direct manipulation to interact with objects when possible. It’s more immersive and intuitive when people can interact with onscreen 3D objects by touching them directly, than by using indirect controls in screen space. However, in situations where people are moving around as they use your app, indirect controls can work better." }, { "type": "paragraph", "text": "Direct manipulation" }, { "type": "paragraph", "text": "Indirect controls" }, { "type": "paragraph", "text": "Let people directly interact with virtual objects using standard, familiar gestures. For example, consider supporting a single-finger drag gesture for moving objects, and a two-finger rotation gesture for spinning objects. For guidance, see Gestures." }, { "type": "paragraph", "text": "In general, keep interactions simple. Touch gestures are inherently two-dimensional, but an AR experience involves the three dimensions of the real world. Consider the following approaches to simplifying people’s interactions with virtual objects." }, { "type": "paragraph", "text": "Limit movement to the two-dimensional surface on which the object rests." }, { "type": "paragraph", "text": "Limit object rotation to a single axis." }, { "type": "paragraph", "text": "Respond to gestures within reasonable proximity of interactive virtual objects. It can be difficult for people to be precise when aiming to touch specific points on objects that are small, thin, or placed at a distance. When your app detects a gesture near an interactive object, it’s usually best to assume that people want to affect that object." }, { "type": "paragraph", "text": "Let people initiate object scaling when it makes sense in your app. For example, if your app lets people explore an imaginary environment, it probably makes sense to support object scaling because your app doesn’t need to represent the real world. On the other hand, if your app helps shoppers decide on furniture to buy, letting people scale a chair object doesn’t help them visualize how the chair will look in a room." }, { "type": "tip", "text": "TipRegardless of the purpose of your app, don’t use scaling as a way to adjust the distance of an object. If you enlarge a distant object in an effort to make it appear closer, the result is a larger object that still looks far away." }, { "type": "paragraph", "text": "Be wary of potentially conflicting gestures. A two-finger pinch gesture, for example, is similar to a two-finger rotation gesture. If you implement two similar gestures like this, be sure to test your app and make sure they’re interpreted properly." }, { "type": "paragraph", "text": "Strive for virtual object movement that’s consistent with the physics of your app’s AR environment. People don’t necessarily expect an object to move smoothly over a rough or uneven surface, but they do expect objects to remain visible during movement. Aim to keep moving objects attached to real-world surfaces and avoid causing objects to jump or vanish and reappear as people resize, rotate, or move them." }, { "type": "paragraph", "text": "Explore even more engaging methods of interaction. Gestures aren’t the only way for people to interact with virtual objects in AR. Your app can use other factors, like motion and proximity, to bring content to life. A game character, for example, could turn its head to look at a person as they walk toward it." } ] }, { "heading": "Offering a multiuser experience", "level": 2, "content": [ { "type": "paragraph", "text": "When multiple people share your app’s AR experience, each participant maps the environment independently and ARKit automatically merges the maps. For developer guidance, see isCollaborationEnabled." }, { "type": "paragraph", "text": "Consider allowing people occlusion. If your app supports placing virtual objects behind people who appear in the device’s camera feed, enhance the illusion of reality by letting the people occlude the objects. For developer guidance, see Occluding virtual content with people." }, { "type": "paragraph", "text": "When possible, let new participants enter a multiuser AR experience. Unless your app requires all participants to join before the experience begins, consider using implicit map merging to let new people quickly join an ongoing AR experience. For developer guidance, see isCollaborationEnabled." } ] }, { "heading": "Reacting to real-world objects", "level": 2, "content": [ { "type": "paragraph", "text": "You can enhance an AR experience by using known images and objects in the real-world environment to make virtual content appear. For example, an app that recognizes theater posters for a sci-fi film could cause virtual space ships to emerge from the posters and fly around the environment. Another example is an app for an art museum that presents a virtual tour guide when it recognizes a sculpture. To support experiences like these, your app provides a set of 2D reference images or 3D reference objects, and ARKit indicates when and where it detects any of these items in the current environment. For developer guidance, see Detecting Images in an AR Experience." }, { "type": "paragraph", "text": "When a detected image first disappears, consider delaying the removal of virtual objects that are attached to it. ARKit doesn’t track changes to the position or orientation of each detected image. To help prevent virtual objects from flickering, consider waiting up to one second before fading them out or removing them." }, { "type": "paragraph", "text": "Limit the number of reference images in use at one time. Image detection performance works best when ARKit looks for 100 or fewer distinct images in the real-world environment. If you need more than 100 reference images, you can change the set of active reference images based on context. For example, a museum guide app could ask permission to use location services to determine the part of the museum a person is in, and then look only for images displayed in that area." }, { "type": "paragraph", "text": "Limit the number of reference images requiring an accurate position. Updating the position of a reference image requires more resources. Use a tracked image when the image may move in the environment or when an attached animation or virtual object is small compared to the size of the image." } ] }, { "heading": "Communicating with people", "level": 2, "content": [ { "type": "paragraph", "text": "If you must display instructional text, use approachable terminology. AR is an advanced concept that may be intimidating to some people. To help make it approachable, avoid using technical terms like ARKit, world detection, and tracking. Instead, use friendly, conversational terms that most people will understand." }, { "type": "table", "rows": [ [ "Do", "Don’t" ], [ "Unable to find a surface. Try moving to the side or repositioning your phone.", "Unable to find a plane. Adjust tracking." ], [ "Tap a location to place the [name of object to be placed].", "Tap a plane to anchor an object." ], [ "Try turning on more lights and moving around.", "Insufficient features." ], [ "Try moving your phone more slowly.", "Excessive motion detected." ] ] }, { "type": "paragraph", "text": "In a three-dimensional context, prefer 3D hints. For example, placing a 3D rotation indicator around an object is more intuitive than displaying text-based instructions in a 2D overlay. Avoid displaying textual overlay hints in a 3D context unless people aren’t responding to contextual hints." }, { "type": "paragraph", "text": "Prefer a 3D hint in a 3D context." }, { "type": "paragraph", "text": "If necessary, use a 2D hint in a 3D context." }, { "type": "paragraph", "text": "Make important text readable. Use screen space to display text used for critical labels, annotations, and instructions. If you need to display text in 3D space, make sure the text faces people and that you use the same type size regardless of the distance between the text and the labeled object." }, { "type": "paragraph", "text": "If necessary, provide a way to get more information. Design a visual indicator that fits with your app experience to show people that they can tap for more information." }, { "type": "paragraph", "text": "Camera view" }, { "type": "paragraph", "text": "Detail view" } ] }, { "heading": "Handling interruptions", "level": 2, "content": [ { "type": "paragraph", "text": "ARKit can’t track device position and orientation during an interruption, such as when people briefly switch to another app or accept a phone call. After an interruption ends, previously placed virtual objects are likely to appear in the wrong real-world positions. When you support relocalization, ARKit attempts to restore those virtual objects to their original real-world positions using new information. For developer guidance, see Managing Session Life Cycle and Tracking Quality." }, { "type": "paragraph", "text": "Consider using the system-provided coaching view to help people relocalize. During relocalization, ARKit attempts to reconcile its previous state with new observations of the current environment. To make these observations more useful, you can use the coaching view to help people return the device to its previous position and orientation." }, { "type": "paragraph", "text": "Consider hiding previously placed virtual objects during relocalization. To avoid flickering or other unpleasant visual effects during relocalization, it can be best to hide virtual objects and redisplay them in their new positions." }, { "type": "paragraph", "text": "Minimize interruptions if your app supports both AR and non-AR experiences. One way to avoid interruptions is by embedding a non-AR experience within an AR experience so that people can handle the task without exiting and re-entering AR. For example, if your app helps people decide on a piece of furniture to purchase by placing the item in a room, you might let them change the upholstery without leaving the AR experience." }, { "type": "paragraph", "text": "Allow people to cancel relocalization. If people don’t position and orient their device near where it was before an interruption, relocalization continues indefinitely without success. If coaching people to resume their session isn’t successful, consider providing a reset button or other way to restart the AR experience." }, { "type": "paragraph", "text": "Indicate when the front-facing camera is unable to track a face for more than about half a second. Use a visual indicator to indicate that the camera can no longer track the person’s face. If you need to provide text instructions in this situation, keep them to a minimum." } ] }, { "heading": "Suggesting problem resolutions", "level": 2, "content": [ { "type": "paragraph", "text": "Let people reset the experience if it doesn’t meet their expectations. Don’t force people to wait for conditions to improve or struggle with object placement. Give them a way to start over again and see if they have better results." }, { "type": "paragraph", "text": "Sufficient lighting" }, { "type": "paragraph", "text": "Insufficient lighting" }, { "type": "paragraph", "text": "Suggest possible fixes if problems occur. Analysis of the real-world environment and surface detection can fail or take too long for a variety of reasons — insufficient light, an overly reflective surface, a surface without enough detail, or too much camera motion. If your app is notified of these problems, use straightforward, friendly language to offer suggestions for resolving them." }, { "type": "table", "rows": [ [ "Problem", "Possible suggestion" ], [ "Insufficient features detected.", "Try turning on more lights and moving around." ], [ "Excessive motion detected.", "Try moving your phone slower." ], [ "Surface detection takes too long.", "Try moving around, turning on more lights, and making sure your phone is pointed at a sufficiently textured surface." ] ] } ] }, { "heading": "Icons and badges", "level": 2, "content": [ { "type": "paragraph", "text": "Apps can display an AR icon in controls that launch ARKit-based experiences. You can download this icon in Resources." }, { "type": "paragraph", "text": "Use the AR glyph as intended. The glyph is strictly for initiating an ARKit-based experience. Never alter the glyph (other than adjusting its size and color), use it for other purposes, or use it in conjunction with AR experiences not created using ARKit." }, { "type": "paragraph", "text": "Maintain minimum clear space. The minimum amount of clear space required around an AR glyph is 10% of the glyph’s height. Don’t let other elements infringe on this space or occlude the glyph in any way." }, { "type": "paragraph", "text": "Apps that include collections of products or other objects can use badging to identify specific items that can be viewed in AR using ARKit. For example, an app that sells vintage collectibles might use a badge to mark items that people can preview in their home before making a purchase." }, { "type": "paragraph", "text": "Use the AR badges as intended and don’t alter them. You can download AR badges, available in collapsed and expanded form, in Resources. Use these images exclusively to identify products or other objects that can be viewed in AR using ARKit. Never alter the badges, change their color, use them for other purposes, or use them in conjunction with AR experiences not created with ARKit." }, { "type": "paragraph", "text": "AR badge" }, { "type": "paragraph", "text": "Glyph-only AR badge" }, { "type": "paragraph", "text": "Prefer the AR badge to the glyph-only badge. In general, use the glyph-only badge for constrained spaces that can’t accommodate the AR badge. Both badges work well at their default size." }, { "type": "paragraph", "text": "Use badging only when your app contains a mixture of objects that can be viewed in AR and objects that cannot. If all objects in your app can be viewed in AR, then badging is redundant." }, { "type": "paragraph", "text": "Keep badge placement consistent and clear. A badge looks best when displayed in one corner of an object’s photo. Always place it in the same corner and make sure it’s large enough to be seen clearly (but not so large that it occludes important detail in the photo)." }, { "type": "paragraph", "text": "Maintain minimum clear space. The minimum amount of clear space required around an AR badge is 10% of the badge’s height. Don’t allow other elements to infringe on this space and occlude the badge in any way." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, or watchOS." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "With the wearer’s permission, you can use ARKit in your visionOS app to detect surfaces in a person’s surroundings, use a person’s hand and finger postions to inform your custom gestures, support interactions that incorporate nearby physical objects into your immersive experience, and more. For developer guidance, see ARKit." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Playing haptics" }, { "type": "paragraph", "text": "Gestures" }, { "type": "paragraph", "text": "Apple Design Resources" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "ARKit" } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/augmented-reality#Best-practices" }, { "title": "Playing audio", "url": "/design/human-interface-guidelines/playing-audio" }, { "title": "Playing haptics", "url": "/design/human-interface-guidelines/playing-haptics" }, { "title": "Providing coaching", "url": "/design/human-interface-guidelines/augmented-reality#Providing-coaching" }, { "title": "Handling interruptions", "url": "/design/human-interface-guidelines/augmented-reality#Handling-interruptions" }, { "title": "Helping people place objects", "url": "/design/human-interface-guidelines/augmented-reality#Helping-people-place-objects" }, { "title": "Designing object interactions", "url": "/design/human-interface-guidelines/augmented-reality#Designing-object-interactions" }, { "title": "Gestures", "url": "/design/human-interface-guidelines/gestures" }, { "title": "Offering a multiuser experience", "url": "/design/human-interface-guidelines/augmented-reality#Offering-a-multiuser-experience" }, { "title": "Reacting to real-world objects", "url": "/design/human-interface-guidelines/augmented-reality#Reacting-to-real-world-objects" }, { "title": "Communicating with people", "url": "/design/human-interface-guidelines/augmented-reality#Communicating-with-people" }, { "title": "Suggesting problem resolutions", "url": "/design/human-interface-guidelines/augmented-reality#Suggesting-problem-resolutions" }, { "title": "Icons and badges", "url": "/design/human-interface-guidelines/augmented-reality#Icons-and-badges" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/augmented-reality#Platform-considerations" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/augmented-reality#visionOS" }, { "title": "permission", "url": "/design/human-interface-guidelines/privacy#visionOS" }, { "title": "custom gestures", "url": "/design/human-interface-guidelines/gestures#Designing-custom-gestures-in-visionOS" }, { "title": "immersive experience", "url": "/design/human-interface-guidelines/immersive-experiences" }, { "title": "Resources", "url": "/design/human-interface-guidelines/augmented-reality#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/augmented-reality#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/augmented-reality#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/augmented-reality#Videos" } ], "image_count": 0 }, { "title": "CarPlay", "url": "https://developer.apple.com/design/human-interface-guidelines/carplay", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "People download CarPlay apps from the App Store and install them on iPhone like any other app. When people connect their iPhone with their vehicle, app icons for installed CarPlay apps appear on the CarPlay Home screen." }, { "type": "paragraph", "text": "CarPlay is designed for drivers to use while they’re driving. Keep this context in mind as you design your CarPlay app, providing features that help people perform tasks quickly and with minimal interaction." }, { "type": "paragraph", "text": "To create the interface of your CarPlay app, you use the system-defined templates that are appropriate for the type of app you’re developing, such as audio, communication, navigation, or fueling. For each template, your app provides the content and iOS renders it in CarPlay. Because the system displays UI components and handles the interface with the vehicle, you don’t need to adjust your layout for different screen resolutions, or manage input from different types of hardware like touchscreens, knobs, or touch pads." }, { "type": "paragraph", "text": "To learn how to create various types of CarPlay apps and use the system-provided templates, see CarPlay App Programming Guide. The general design guidelines below apply to all types of CarPlay apps." } ] }, { "heading": "iPhone interactions", "level": 2, "content": [ { "type": "paragraph", "text": "CarPlay shows compatible apps from the connected iPhone on the car’s built-in display, applying simplified interfaces that are optimized for use while driving." }, { "type": "paragraph", "text": "Eliminate app interactions on iPhone when CarPlay is active. Interactions with your app need to occur using the car’s built-in controls and display. If your app requires setup on iPhone, make sure people perform it before the vehicle is in motion." }, { "type": "paragraph", "text": "Never lock people out of CarPlay because the connected iPhone requires input. Your app needs to function when iPhone is inaccessible — for example, when people put it in a bag or in the trunk while driving. If people must resolve a problem on the connected iPhone, let them do so after the vehicle stops." }, { "type": "paragraph", "text": "Make sure your app works without requiring people to unlock iPhone. Most people use CarPlay while their iPhone is locked, so ensure that the features you provide in your CarPlay app work as expected in this scenario." } ] }, { "heading": "Audio", "level": 3, "content": [ { "type": "paragraph", "text": "In CarPlay, keep in mind that your app coexists with other audio sources, such as the car’s own built-in radio and voice prompts from the navigation system. Regardless of whether audio is a primary aspect of your app’s experience, you need to know how people expect audio to behave so you can meet those expectations." }, { "type": "paragraph", "text": "Let people choose when to start playback. In general, avoid beginning playback automatically unless your app’s purpose is to play a single source of audio, or your app is resuming previously interrupted audio. Also, avoid starting an audio session until you’re ready to actually play audio because starting a session silences other audio sources, like the car’s built-in radio." }, { "type": "paragraph", "text": "Start playback as soon as audio has sufficiently loaded. After people make a selection, it may take several seconds for audio to begin playing, depending on buffering and network conditions. The system keeps the selection highlighted and displays a spinning activity indicator until your app signals that the audio is ready to play." }, { "type": "paragraph", "text": "Display the Now Playing screen when audio is ready to play. Don’t delay playback until descriptive information completes loading. If necessary, continue loading such information in the background, and show it when it’s available." }, { "type": "paragraph", "text": "Resume audio playback after an interruption only when it’s appropriate. For example, your app can resume audio after a temporary interruption like a phone call. Permanent interruptions, such as a music playlist initiated by Siri, are nonresumable. When a resumable interruption occurs, your app needs to resume playback when the interruption ends if audio was actively playing when the interruption started." }, { "type": "paragraph", "text": "When necessary, automatically adjust audio levels, but don’t change the overall volume. Although your app can adjust relative, independent volume levels to achieve a great mix of audio, people need to control the final output volume." } ] }, { "heading": "Layout", "level": 2, "content": [ { "type": "paragraph", "text": "CarPlay supports a wide range of display resolutions with varying pixel densities and aspect ratios. The system automatically scales app icons and interfaces based on the resolution of the display, so they always appear onscreen at roughly the same size. Some common screen sizes are listed in the table below." }, { "type": "table", "rows": [ [ "Dimensions (pixels)", "Aspect ratio" ], [ "800x480", "5:3" ], [ "960x540", "16:9" ], [ "1280x720", "16:9" ], [ "1920x720", "8:3" ] ] }, { "type": "paragraph", "text": "Provide useful, high-value information in a clean layout that’s easy to scan from the driver’s seat. Don’t clutter the screen with nonessential details and unnecessary visual embellishments." }, { "type": "paragraph", "text": "Maintain an overall consistent appearance throughout your app. In general, ensure that elements with similar functions look similar." }, { "type": "paragraph", "text": "Ensure that primary content stands out and feels actionable. Large items tend to appear more important than smaller ones and are easier for people to tap. In general, place the most important content and controls in the upper half of the screen." } ] }, { "heading": "Color", "level": 2, "content": [ { "type": "paragraph", "text": "Color can indicate interactivity, impart vitality, and provide visual continuity." }, { "type": "paragraph", "text": "In general, prefer a limited color palette that coordinates with your app logo. Subtle use of color is a great way to communicate your brand." }, { "type": "paragraph", "text": "Avoid using the same color for interactive and noninteractive elements. If interactive and noninteractive elements have the same color, it’s hard for people to know where to tap." }, { "type": "paragraph", "text": "Test your app’s color scheme under a variety of lighting conditions in an actual car. Lighting varies significantly based on time of day, weather, window tinting, and more. Colors you see on your computer at design time won’t always look the same when your app is used in the real world. Consider how color brightness might affect the experience of driving at night, and how low-contrast colors can wash out in direct sunlight. If necessary, make adjustments to provide the best possible viewing experience in the majority of use cases." }, { "type": "paragraph", "text": "Ensure your app looks great in both dark and light environments. CarPlay supports both light and dark appearances, and may automatically adjust the current appearance based on lighting conditions." }, { "type": "paragraph", "text": "Choose colors that help you communicate effectively with everyone. Different people see and interpret colors differently. For guidance on using colors in ways that people appreciate, see Inclusive color." } ] }, { "heading": "Icons and images", "level": 2, "content": [ { "type": "paragraph", "text": "CarPlay supports both landscape and portrait displays and both @2x (low resolution) and @3x (high resolution) scale factors." }, { "type": "paragraph", "text": "Supply high-resolution images with scale factors of @2x and @3x for all CarPlay artwork in your app. The system automatically shows the correct images and scales them appropriately, based on the resolution and size of the car’s display." }, { "type": "paragraph", "text": "Mirror your iPhone app icon. A well-designed app icon works well in CarPlay and on iPhone, without the need for a second design." }, { "type": "paragraph", "text": "Don’t use black for your icon’s background. Lighten a black background or add a border so the icon doesn’t blend into the display background." }, { "type": "paragraph", "text": "Create your CarPlay app icon in the following sizes:" }, { "type": "table", "rows": [ [ "@2x (pixels)", "@3x (pixels)" ], [ "120x120", "180x180" ] ] } ] }, { "heading": "Error handling", "level": 2, "content": [ { "type": "paragraph", "text": "A CarPlay app needs to handle errors gracefully and report them to people only when absolutely necessary." }, { "type": "paragraph", "text": "Report errors in CarPlay, not on the connected iPhone. If you must notify people of a problem, do so clearly in CarPlay. Never direct people to pick up their iPhone to read or resolve an error." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS. Not supported in iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "CarPlay" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "CarPlay App Programming Guide" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "iPhone interactions", "url": "/design/human-interface-guidelines/carplay#iPhone-interactions" }, { "title": "Audio", "url": "/design/human-interface-guidelines/carplay#Audio" }, { "title": "Layout", "url": "/design/human-interface-guidelines/carplay#Layout" }, { "title": "Color", "url": "/design/human-interface-guidelines/carplay#Color" }, { "title": "Inclusive color", "url": "https://developer.apple.com/design/human-interface-guidelines/color#Inclusive-color" }, { "title": "Icons and images", "url": "/design/human-interface-guidelines/carplay#Icons-and-images" }, { "title": "Error handling", "url": "/design/human-interface-guidelines/carplay#Error-handling" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/carplay#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/carplay#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/carplay#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/carplay#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/carplay#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/carplay#Change-log" } ], "image_count": 0 }, { "title": "CareKit", "url": "https://developer.apple.com/design/human-interface-guidelines/carekit", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "To learn more about CareKit, see Research & Care > CareKit." }, { "type": "paragraph", "text": "CareKit 2.0 contains two projects, CareKit UI and CareKit Store. CareKit UI provides a wide variety of prebuilt views you can use to create a custom CareKit app. CareKit Store defines a database scheme that incorporates CareKit entities — such as patients, care plans, tasks, and contacts — so you can store and manage data on the patient’s device. CareKit 2.0 provides seamless synchronization between your database and the UI, so you can always keep a care plan up to date. For developer guidance, see CareKit." } ] }, { "heading": "Data and privacy", "level": 2, "content": [ { "type": "paragraph", "text": "Nothing is more important than protecting people’s privacy and safeguarding the extremely sensitive data your CareKit app collects and stores." }, { "type": "paragraph", "text": "Provide a coherent privacy policy. During the app submission process, you must provide a URL to a clearly stated privacy policy, so that people can view the policy when they click the link in the App Store page for your app. For developer guidance, see App information > App Store Connect help." }, { "type": "paragraph", "text": "In addition to the data that people enter into your CareKit app, you may be able to access data through iOS features and capabilities. You must receive people’s permission before accessing data through these features, and you must protect people’s data whether people enter it into your app or you get it from the device or the system. For developer guidance, see Protecting user privacy." } ] }, { "heading": "HealthKit integration", "level": 3, "content": [ { "type": "paragraph", "text": "HealthKit is the central repository for health and fitness data in iOS and watchOS. When you support HealthKit in your CareKit app, you can ask people for permission to access and share their health and fitness data with designated caregivers." }, { "type": "paragraph", "text": "Request access to health data only when you need it. It makes sense to request access to weight information when people log their weight, for example, but not immediately after your app launches. When your request is clearly related to the current context, you help people understand your app’s intentions. Also, people can change the permissions they grant, so it’s a good idea to make a request every time your app needs access. For developer guidance, see requestAuthorization(toShare:read:completion:)." }, { "type": "paragraph", "text": "Clarify your app’s intent by adding descriptive messages to the standard permission screen. People expect to see the system-provided permission screen when asked to approve access to health data. Write a few succinct sentences that explain why you need the information and how people can benefit from sharing it with your app. Avoid adding custom screens that replicate the standard permission screen’s behavior or content." }, { "type": "paragraph", "text": "Manage health data sharing solely through the system’s privacy settings. People expect to globally manage access to their health information in Settings > Privacy. Don’t confuse people by building additional screens in your app that affect the flow of health data." }, { "type": "paragraph", "text": "For related design guidance, see HealthKit. For developer guidance, see HealthKit." } ] }, { "heading": "Motion data", "level": 3, "content": [ { "type": "paragraph", "text": "If it’s useful for treatment and if people give permission, your app can get motion information from the device to determine if people are standing still, walking, running, cycling, or driving. When people are walking or running, you can also determine the step count, pace, and number of flights of stairs ascended or descended." }, { "type": "paragraph", "text": "Motion information can also include custom data collected as part of physical therapy. For example, some ResearchKit tasks use device sensors to test flexibility, range of motion, and ambulatory capability." }, { "type": "paragraph", "text": "For developer guidance, see Core Motion." } ] }, { "heading": "Photos", "level": 3, "content": [ { "type": "paragraph", "text": "Pictures are a great way to communicate treatment progress. With people’s permission, your app can access the device’s camera and photos to share pictures with a care team. For example, a care plan might include a request for people to share periodic photos of an injury, so the physician can monitor the healing process." }, { "type": "paragraph", "text": "For developer guidance, see UIImagePickerController." } ] }, { "heading": "ResearchKit integration", "level": 3, "content": [ { "type": "paragraph", "text": "A ResearchKit app lets people participate in important medical research studies. Your CareKit app can incorporate ResearchKit features to display related surveys, tasks, and charts, if appropriate. ResearchKit also includes an informed consent module, which your CareKit app can use to request people’s permission to collect and share data." }, { "type": "paragraph", "text": "For related design guidance, see ResearchKit. For developer guidance, see Research & Care > Developers." } ] }, { "heading": "CareKit views", "level": 2, "content": [ { "type": "paragraph", "text": "CareKit UI provides customizable views organized into three categories — tasks, charts, and contacts — and defines several default view styles in each. To design a CareKit app, you simply choose the view styles you need and supply CareKit Store data to display in them." }, { "type": "paragraph", "text": "Each view category is designed to support specific types of content and interaction. To ensure a consistent experience, use each view type for its intended purpose." }, { "type": "table", "rows": [ [ "Category", "Purpose" ], [ "Tasks", "Present tasks, like taking medication or doing physical therapy. Support logging of patient symptoms and other data." ], [ "Charts", "Display graphical data that can help people understand how their treatment is progressing." ], [ "Contact views", "Display contact information. Support communication through phone, message, and email, and link to a map of the contact’s location." ] ] }, { "type": "paragraph", "text": "Tasks and charts" }, { "type": "paragraph", "text": "Contacts" }, { "type": "paragraph", "text": "A CareKit UI view consists of a header and may include a stack of content subviews. Located at the top of the view, the header can display text, a symbol, and a disclosure indicator, and can include a separator at its bottom edge. The content stack appears below the header and displays your content subviews in a vertical arrangement." }, { "type": "paragraph", "text": "CareKit UI takes care of all the layout constraints within a view, so you don’t have to worry about breaking existing constraints when you add new subviews to the stack." } ] }, { "heading": "Tasks", "level": 3, "content": [ { "type": "paragraph", "text": "A care plan generally presents a set of prescribed actions for people to perform, such as taking medication, eating specific foods, exercising, or reporting symptoms. CareKit UI defines several styles of task views you can use to display prescribed actions. Typically, you customize a task view by providing the information to display, often by specifying data stored in an on-device CareKit Store database. In some cases, you might also supply custom UI elements." }, { "type": "paragraph", "text": "A task can contain the following types of information." }, { "type": "table", "rows": [ [ "Information", "Required", "Description", "Example value" ], [ "Title", "Yes", "A word or short phrase that introduces the task.", "Ibuprofen" ], [ "Schedule", "Yes", "The schedule on which a task must be completed.", "Four times a day" ], [ "Instructions", "No", "Detailed instructions, recommendations, and warnings.", "Take 1 tablet every 4–6 hours (not to exceed 4 tablets daily)." ], [ "Group ID", "No", "An identifier you can use to group similar tasks in ways that make sense in your app.", "A category identifier like medication or exercise." ] ] }, { "type": "paragraph", "text": "In CareKit 2.0, CareKit UI defines five styles of task views: simple, instructions, log, checklist, and grid. Each style is designed to support a particular use case." }, { "type": "paragraph", "text": "Use the simple style for a one-step task. The default simple-style view consists of a header area that contains a title, subtitle, and button. You provide the title and subtitle, and you can provide a custom image to display in the button when the task is complete. If you don’t supply an image, CareKit shows that a task is complete by filling in the button and displaying a checkmark. Because the default simple-style view doesn’t include a content stack, consider using a different task style if you need to display additional content." }, { "type": "paragraph", "text": "Use the instructions style when you need to add informative text to a simple task. For example, if a single-step medication task needs to include additional information — such as “Take on an empty stomach” or “Take at bedtime” — you can use an instructions-style task to display it." }, { "type": "paragraph", "text": "Use the log style to help people log events. For example, you could use this task style to display a button people can tap whenever they feel nauseated. The log-style task can automatically display a timestamp every time the patient logs an event." }, { "type": "paragraph", "text": "Use the checklist style to display a list of actions or steps in a multistep task. For example, if people must take a medication three times per day, you could display the three scheduled times in a checklist. Each checklist item can include a text description and a button that people can tap to mark the item as done. By default, a checklist task can also display instructional text below the list." }, { "type": "paragraph", "text": "Use the grid style to display a grid of buttons in a multistep task. Like the checklist style, the grid style also supports a multistep task, but it displays the steps in a more compact arrangement. You can supply a succinct title for each button (if you need to provide additional description for each button, you might want to use the checklist style instead). By default, a grid-style task can also display instructional text below the grid of buttons. Unlike other task styles, the grid style gives you access to its underlying collection view, which means that you can display custom UI elements in the grid layout." }, { "type": "paragraph", "text": "Consider using color to reinforce the meaning of task items. Color can be a good way to help people understand information at a glance. For example, you could use one color for medications and a different color for physical activities. Always avoid using color as the only way to convey information. For guidance, see Color." }, { "type": "paragraph", "text": "Combine accuracy with simplicity when describing a task and its steps. For example, use a medication’s marketing name instead of its chemical description. Also, when the context of a task helps to clarify meaning, minimize the number of words you use. For example, a daily medication task generally tells people when to take specific medications, so it may be unnecessary to repeat words like take." }, { "type": "paragraph", "text": "Consider supplementing multistep or complex tasks with videos or images. Visually demonstrating how to perform a task can help people avoid mistakes." } ] }, { "heading": "Charts", "level": 3, "content": [ { "type": "paragraph", "text": "Chart views let you present data and trends in graphical ways that can help people visualize their progress in a care plan. CareKit chart views can display both current and historical data, and update automatically with new data." }, { "type": "paragraph", "text": "In CareKit 2.0, CareKit UI provides three chart styles: bar, scatter, and line. For each style, you provide a descriptive title and subtitle, supply axis markers — like days of the week — and specify the data set." }, { "type": "paragraph", "text": "Bar chart" }, { "type": "paragraph", "text": "Scatter chart" }, { "type": "paragraph", "text": "Line chart" }, { "type": "paragraph", "text": "Consider highlighting narratives and trends to illustrate progress. For example, your app could display a bar chart that shows a correlation between the number of times people took medication and their level of pain. Displaying such data can encourage better adherence to a care plan." }, { "type": "paragraph", "text": "Label chart elements clearly and succinctly. Long, detailed labels can make a chart difficult to read and understand. Keep labels short and avoid repeating the same information. For example, a heart rate chart might use the term BPM in an axis label instead of using it in the label of every data point." }, { "type": "paragraph", "text": "Use distinct colors. In general, avoid using different shades of the same color to mean different things. Also ensure that you use colors with sufficient contrast. For related guidance, see Accessibility." }, { "type": "paragraph", "text": "Consider providing a legend to add clarity. If the colors you use to represent different types of data aren’t immediately clear, include a legend that clearly and succinctly describes them." }, { "type": "paragraph", "text": "Clearly denote units of time. People need to know whether time-based data is represented in seconds, minutes, hours, days, weeks, months, or years. If you don’t want to include this information in individual data value labels, include it in an axis label or elsewhere on the chart." }, { "type": "paragraph", "text": "Consolidate large data sets for greater readability. A large amount of data can make a chart unreadable by reducing the size of individual data points and presenting too much visible information. Look for ways to group and organize data for clarity and simplicity." }, { "type": "paragraph", "text": "If necessary, offset data to keep charts proportional. It’s easy for very small data points to get lost or become unreadable in a chart that also contains very large data points. If the difference between data points is significant, find ways to offset or restructure the data so all data points are readable." }, { "type": "paragraph", "text": "For developer guidance, see CareKit > Chart Interfaces. To learn about ResearchKit charts, see the ResearchKit GitHub project." } ] }, { "heading": "Contact views", "level": 3, "content": [ { "type": "paragraph", "text": "A care plan typically includes a care team and other trusted individuals who can help patients follow the plan. CareKit UI defines a contact view you can use to help patients communicate with the people in their care plan." }, { "type": "paragraph", "text": "In CareKit 2.0, CareKit UI provides two styles of the contact view: simple and detailed." }, { "type": "paragraph", "text": "Simple" }, { "type": "paragraph", "text": "Detailed" }, { "type": "paragraph", "text": "Consider using color to categorize care team members. Color can help people identify care team members at a glance." } ] }, { "heading": "Notifications", "level": 2, "content": [ { "type": "paragraph", "text": "Notifications can tell people when it’s time to take medication or complete a task, and badging your app icon can show that there’s an unread message from a caregiver. Apple Watch can also display a notification from your app; for guidance, see Notifications." }, { "type": "paragraph", "text": "Minimize notifications. Care plans vary from patient to patient. While one individual may have only a few daily tasks to complete, another may have a long list. Use notifications sparingly so people don’t feel overwhelmed. When possible, consider coalescing multiple items into a single notification." }, { "type": "paragraph", "text": "Consider providing a detail view. In addition to providing more information, a notification detail view can help people take immediate action without leaving their current context to open your app. For example, you could use a notification detail view to display a list of pending tasks so that people can quickly mark them as complete." } ] }, { "heading": "Symbols and branding", "level": 2, "content": [ { "type": "paragraph", "text": "CareKit uses a variety of built-in symbols to help people understand what they can do in a care app. For example, CareKit can display the phone, messaging, and envelope symbols in a contact view and the clock symbol in a log-style task view." }, { "type": "paragraph", "text": "Although you can customize the default symbols, most view styles work best with the CareKit-provided symbols. The exception is the highly customizable grid-style task view, which can display your custom UI in a grid layout." }, { "type": "paragraph", "text": "In a grid view, you might want to display custom symbols that are relevant to the unique content and experience in your app. You could use symbols to indicate the grouping of tasks; for example, a pill to represent medication tasks, or a person walking to represent exercise tasks. In this scenario, consider using SF Symbols to illustrate custom items in your app." }, { "type": "paragraph", "text": "Using SF Symbols in your app gives you:" }, { "type": "list", "items": [ "Designs that coordinate with CareKit’s visual design language", "Support for creating custom symbols to represent the unique content in your app" ] }, { "type": "paragraph", "text": "Design a relevant care symbol. If you need to customize a symbol, be sure the design is closely related to your app or the general concept of health and wellness. Avoid creating a purely decorative symbol or using a corporate logo as a custom symbol." }, { "type": "paragraph", "text": "Incorporate refined, unobtrusive branding. People use CareKit apps to help them achieve their health and wellness goals; they don’t want to see advertising. To avoid distracting people from their care plan, subtly incorporate your brand through your app’s use of color and communication style." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Research & Care > CareKit" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "CareKit" }, { "type": "paragraph", "text": "Research & Care > Developers" }, { "type": "paragraph", "text": "Protecting user privacy — HealthKit" }, { "type": "paragraph", "text": "HealthKit" }, { "type": "paragraph", "text": "ResearchKit GitHub project" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Data and privacy", "url": "/design/human-interface-guidelines/carekit#Data-and-privacy" }, { "title": "HealthKit integration", "url": "/design/human-interface-guidelines/carekit#HealthKit-integration" }, { "title": "HealthKit", "url": "/design/human-interface-guidelines/healthkit" }, { "title": "Motion data", "url": "/design/human-interface-guidelines/carekit#Motion-data" }, { "title": "Photos", "url": "/design/human-interface-guidelines/carekit#Photos" }, { "title": "ResearchKit integration", "url": "/design/human-interface-guidelines/carekit#ResearchKit-integration" }, { "title": "ResearchKit", "url": "/design/human-interface-guidelines/researchkit" }, { "title": "CareKit views", "url": "/design/human-interface-guidelines/carekit#CareKit-views" }, { "title": "Tasks", "url": "/design/human-interface-guidelines/carekit#Tasks" }, { "title": "Charts", "url": "/design/human-interface-guidelines/carekit#Charts" }, { "title": "Contact views", "url": "/design/human-interface-guidelines/carekit#Contact-views" }, { "title": "Color", "url": "/design/human-interface-guidelines/color" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Notifications", "url": "/design/human-interface-guidelines/carekit#Notifications" }, { "title": "Notifications", "url": "/design/human-interface-guidelines/notifications" }, { "title": "Symbols and branding", "url": "/design/human-interface-guidelines/carekit#Symbols-and-branding" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/carekit#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/carekit#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/carekit#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/carekit#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/carekit#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/carekit#Change-log" } ], "image_count": 0 }, { "title": "Game Center", "url": "https://developer.apple.com/design/human-interface-guidelines/game-center", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Supporting Game Center in your game allows players to:" }, { "type": "list", "items": [ "Discover new games their friends are playing.", "Seamlessly invite friends to play.", "See the latest activity from their games across the system, in the Apple Games app, the App Store, notifications, and more." ] }, { "type": "paragraph", "text": "By enabling the player activities listed above, supporting Game Center also helps surface your game to more players across Apple platforms." }, { "type": "paragraph", "text": "You can add Game Center into your game using the GameKit framework, which provides a full-featured UI that makes it easy for players to access and view their Game Center data within your game. Alternatively, you can also use GameKit to present this data within your own custom UI. For developer guidance, see GameKit." } ] }, { "heading": "Accessing Game Center", "level": 2, "content": [ { "type": "paragraph", "text": "To provide the best Game Center experience for your players, begin by determining whether the player is signed in to their Game Center account on the system when they launch your game. If they aren’t, initialize the player with Game Center at that time. This provides the most seamless user experience, and maximizes discovery opportunities for your game, such as in the Top Played chart and in social recommendations through players’ friends." } ] }, { "heading": "Integrating the access point", "level": 3, "content": [ { "type": "paragraph", "text": "The Game Center access point is an Apple-designed UI element that lets players view their Game Center profile and information without leaving your game. For developer guidance, see Adding an access point to your game." }, { "type": "paragraph", "text": "In iOS, iPadOS, and macOS the access point leads players to the Game Overlay, a system overlay that allows players to view their progress and start game activities." }, { "type": "paragraph", "text": "In visionOS and tvOS, the access point leads players to the in-game dashboard, a full-screen view of a player’s Game Center activity that appears on top of your game." }, { "type": "paragraph", "text": "Display the access point in menu screens. Consider adding the access point to the main menu or the settings area of your game. Avoid displaying the access point during active gameplay or in temporary splash screens, cinematic flows, or tutorials that might precede your game’s main menu screen." }, { "type": "paragraph", "text": "Avoid placing controls near the access point. You can choose to present the access point at any of the four corners of the screen in a fixed position. Remember that the access point has both a collapsed and expanded version, so check whether the access point overlaps any important UI and controls and adjust your layout accordingly." }, { "type": "note", "text": "NoteIn visionOS, the locations of the access point vary based on game type, such as immersive or volume-based. For developer guidance, see Adding an access point to your game." }, { "type": "paragraph", "text": "Consider pausing your game while the Game Overlay or dashboard is present. Pausing your game can help players view their Game Center information without feeling like the game is continuing without them." } ] }, { "heading": "Using custom UI", "level": 3, "content": [ { "type": "paragraph", "text": "Your game can include custom links into the Game Overlay (in iOS, iPadOS, macOS) or the dashboard (in visionOS and tvOS). Your custom UI can deep-link into specific areas within both such as leaderboards or a player’s Game Center profile." }, { "type": "paragraph", "text": "Use the artwork Game Center provides in custom links. When referencing Game Center features in custom UI, use the official artwork from Apple Design Resources. Preserve the appearance of this artwork and don’t adjust the dimensions or visual effects." }, { "type": "paragraph", "text": "Use the correct terminology in custom links. The following table describes how to use Game Center terminology correctly so that you can avoid confusing players in custom UI." }, { "type": "table", "rows": [ [ "Term", "Incorrect terms", "Localization" ], [ "Game Center", "GameKit, GameCenter, game center", "Use the system-provided translation of Game Center" ], [ "Game Center Profile", "Profile, Account, Player Info", "Use the system-provided translation of Game Center and localize Profile" ], [ "Achievements", "Awards, Trophies, Medals", "" ], [ "Leaderboards", "Rankings, Scores, Leaders", "" ], [ "Challenges", "Competitions", "" ], [ "Add Friends", "Add, Add Profiles, Include Friends", "" ] ] } ] }, { "heading": "Achievements", "level": 2, "content": [ { "type": "paragraph", "text": "Achievements give players an added incentive to stay engaged with your game. Game Center achievements appear in a collectible card format that highlights the player’s progress and showcases your artwork. For developer guidance, see Rewarding players with achievements." }, { "type": "paragraph", "text": "Achievements overview" }, { "type": "paragraph", "text": "Achievement detail" } ] }, { "heading": "Integrating achievements into your game", "level": 3, "content": [ { "type": "paragraph", "text": "Align with Game Center achievement states. Game Center defines four achievement states: locked, in-progress, hidden, and completed. The system groups achievements by completion status, displaying completed achievements in the Completed group and all other achievements in the Locked group. When you map your achievements to the four Game Center achievement states, you give players a consistent experience and you help them see at a glance the types of achievements your game offers." }, { "type": "paragraph", "text": "Determine a display order. The order in which you upload achievements is the order in which they appear, so consider the order you want before uploading files. For example, you might want your achievements to appear in an order that corresponds to the most common path through your game." }, { "type": "paragraph", "text": "Be succinct when describing achievements. The achievement card limits the title and description to two lines each. If your title or description wraps beyond two lines, the card truncates the text. Use title-style capitalization for the achievement title and sentence-style capitalization for the description." }, { "type": "paragraph", "text": "Give players a sense of progress. When you use progressive achievements, the system displays player progress and provides encouraging messages like “Youʼre more than halfway to completing Great Lakes Freighter in The Coast. Keep going!” to help motivate players to complete them." } ] }, { "heading": "Creating achievement images", "level": 3, "content": [ { "type": "paragraph", "text": "Design rich, high-quality images that help players feel rewarded. Achievements are a prominent feature in Game Center UI, so it’s essential to design high-quality assets that catch the eye and encourage players to return to your game. Avoid reusing the same asset to represent more than one achievement. If you don’t provide an asset for an achievement, the card shows a placeholder image instead." }, { "type": "paragraph", "text": "Create artwork in the appropriate size and format. The system applies a circular mask to your achievement image, so be sure to keep content centered. Use the following specifications to create images." }, { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Format", "PNG, TIF, or JPG" ], [ "Color space", "sRGB or P3" ], [ "Resolution", "72 DPI (minimum)" ], [ "Image size", "512x512 pt (1024x1024 px @2x)" ], [ "Mask diameter", "512 pt (1024 px @2x)" ] ] }, { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Format", "PNG, TIF, or JPG" ], [ "Color space", "sRGB or P3" ], [ "Resolution", "72 DPI (minimum)" ], [ "Image size", "320x320 pt (640x640 px @2x)" ], [ "Mask diameter", "200 pt (400 px @2x)" ] ] } ] }, { "heading": "Leaderboards", "level": 2, "content": [ { "type": "paragraph", "text": "Leaderboards are a great way to encourage friendly competition within your game. When you adopt Game Center, players can easily check their ranking against friends and global players as well as receive notifications when their friends challenge them or pass their score on a leaderboard. You can take advantage of the system-designed UI or present leaderboard information within custom UI. For developer guidance, see Encourage progress and competition with leaderboards." }, { "type": "paragraph", "text": "Leaderboards overview" }, { "type": "paragraph", "text": "Leaderboard detail" }, { "type": "paragraph", "text": "Choose a leaderboard type. Game Center supports two types of leaderboards: classic and recurring." }, { "type": "list", "items": [ "A classic leaderboard tracks a player’s best all-time score. Classic leaderboards are always active with no ending. The following are examples of goals you might include in a classic leaderboard:Strive for the most perfect score in a rhythm game.Collect the most coins in a single dungeon run.Achieve the longest continuous time in an endless runner.", "A recurring leaderboard resets based on a time interval you define, such as every week or every day. Recurring leaderboards can increase engagement by giving players more chances to take the lead. The following are examples of features that work well with recurring leaderboards:Daily rotating puzzlesSeasonal or holiday-themed eventsWeekly leaderboards for different battle modes" ] }, { "type": "paragraph", "text": "Take advantage of leaderboard sets for multiple leaderboards. Leaderboard sets are an organization system that can make it easier for players to find the board they’re looking for. Consider grouping leaderboard sets by themes or gameplay experiences, such as:" }, { "type": "list", "items": [ "Difficulty modes (Easy, Standard, Hard)", "Activity types (Combat, Crafting, Farming)", "Genres and themes (Disco, Pop, Rock)" ] }, { "type": "paragraph", "text": "Add leaderboard images. Leaderboard artwork gives you another opportunity to reinforce your game’s visual aesthetic. Aim to create a unique image for each leaderboard in your game that reflects and showcases the gameplay involved in leaderboard ranking. Leaderboards appear across the system, promoting ways for players to engage and compete with friends, and having compelling images helps attract players and gives them a sense of the experience." }, { "type": "paragraph", "text": "For games that run in iOS, iPadOS, and macOS, use a single image for your leaderboard image. For games that run in tvOS, provide a set of images that animate when the artwork is in focus. To learn more about focus effects, see Focus and selection. For help creating focusable images, download the tvOS template from Apple Design Resources. Use the following specifications to create leaderboard artwork." }, { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Format", "JPEG, JPG, or PNG" ], [ "Color space", "sRGB or P3" ], [ "Resolution", "72 DPI (minimum)" ], [ "Image size", "512x512 pt (1024x1024 px @2x)" ], [ "Cropped area", "512x312 pt (1024x624 px @2x)" ] ] }, { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Format", "PNG, TIF, or JPG" ], [ "Color space", "sRGB or P3" ], [ "Resolution", "72 DPI (minimum)" ], [ "Image size", "659x371 pt (1318x742 px @2x)" ], [ "Focused size", "618x348 pt (1236x696 px @2x)" ], [ "Unfocused size", "548x309 pt (1096x618 px @2x)" ] ] }, { "type": "note", "text": "NoteBe mindful of how cropping might affect your leaderboard artwork. In iOS, iPadOS, and macOS, the system crops artwork for leaderboards that are part of a leaderboard set. In tvOS, the focus effect on leaderboard artwork may crop your images at the edges of some layers. Make sure your primary content stays comfortably visible in both these scenarios." } ] }, { "heading": "Challenges", "level": 2, "content": [ { "type": "paragraph", "text": "Challenges turn single player activities into multiplayer experiences with friends. Challenges are built on top of leaderboards and allow players to connect with their friends and participate in competitions with time limits. For developer documentation, see Creating engaging challenges from leaderboards." }, { "type": "paragraph", "text": "Challenges overview" }, { "type": "paragraph", "text": "Challenge detail" }, { "type": "paragraph", "text": "Create engaging challenges. Challenges are great for short, skill-based gameplay activities that have a clear way of gauging players’ accomplishments. Create challenges that take 1-5 minutes to play, with gameplay that players can complete individually. Examples of compelling challenges are:" }, { "type": "list", "items": [ "Complete the fastest lap in a racing level.", "Defeat the most enemies in a single round.", "Solve a daily puzzle with the fewest mistakes." ] }, { "type": "paragraph", "text": "Avoid creating challenges that track overall progress or personal best scores. These can give regular players an unfair advantage. Instead, track players’ most recent score after each attempt at your challenge. This helps keep your challenge motivating by placing all players on a level playing field." }, { "type": "paragraph", "text": "Make it easy to jump into your challenge. Players can access challenges through invitation links, the Game Overlay, or in the Games app in iOS, iPadOS, and macOS. Always deep-link to the exact mode or level where your challenge begins, and help first-time players complete any initial onboarding before beginning the challenge. For example, if your game requires a tutorial level to understand basic controls, launch the player into the tutorial first and present UI that lets them know your game automatically jumps into the challenge afterward." }, { "type": "paragraph", "text": "Create high-quality artwork that encourages players to engage with your challenges. The system shows your challenge’s artwork in the Game Overlay, Games app, and in the preview of an invitation link. Avoid placing the primary content of your artwork in an area where the challenge’s title and description might cover it. If you need to use text in your challenge image, provide the appropriate localized versions through App Store Connect or Xcode. Use the following specifications to create challenge artwork." }, { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Format", "JPEG, JPG, or PNG" ], [ "Color space", "sRGB or P3" ], [ "Resolution", "72 DPI (minimum)" ], [ "Image size", "1920x1080 pt (3840x2160 px @2x)" ], [ "Cropped area", "1465x767 pt (2930x1534 px @2x)" ] ] } ] }, { "heading": "Multiplayer activities", "level": 2, "content": [ { "type": "paragraph", "text": "Game Center supports both real-time and turn-based multiplayer activities that make it easy to connect players with friends or other players. Players can access multiplayer gameplay through party codes, the Game Overlay, the dashboard, or in the Games app. For developer documentation, see Creating activities for your game." }, { "type": "paragraph", "text": "Multiplayer levels overview" }, { "type": "paragraph", "text": "Multiplayer level detail" }, { "type": "paragraph", "text": "Use party codes to invite players to multiplayer activities. Game Center party codes are a great way to coordinate real-time multiplayer sessions whether you use Game Center matchmaking and networking facilities or provide your own. Game Center generates alpha-numeric party codes that are typically eight characters long, such as “2MP4-9CMF.” When integrating party codes into your multiplayer games, consider the following guidelines for the best player experience:" }, { "type": "list", "items": [ "Allow players to join gameplay late, leave early, and return later.", "Provide a way for players to view the current party code in your game.", "Allow players to enter a party code manually." ] }, { "type": "paragraph", "text": "Support multiplayer activities through in-game UI. The Game Overlay and Game Center dashboard help players find other people for a multiplayer match without leaving your game. Game Center’s default multiplayer interface lets a player invite nearby or recent players, Game Center friends, and contacts. You can also choose to present multiplayer functionality within your custom UI. For developer guidance, see Finding multiple players for a game." }, { "type": "paragraph", "text": "Provide engaging activity artwork. Players see the preview image for a multiplayer activity throughout the system, such as in a party code, the Games app, or in-game UI. Use the following specifications to create your artwork." }, { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Format", "JPEG, JPG, or PNG" ], [ "Color space", "sRGB or P3" ], [ "Resolution", "72 DPI (minimum)" ], [ "Image size", "1920x1080 pt (3840x2160 px @2x)" ], [ "Cropped area", "1465x767 pt (2930x1534 px @2x)" ] ] } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, or visionOS." } ] }, { "heading": "tvOS", "level": 3, "content": [ { "type": "paragraph", "text": "Display an optional image at the top of the dashboard. In tvOS, you can add an additional piece of artwork to the dashboard to highlight your game’s aesthetic. Use a simple, easily recognizable image that looks great at a distance. Consider using your game’s logo or word mark; however, don’t use your app icon for this image. Use the following specifications to create a dashboard image." }, { "type": "table", "rows": [ [ "Attribute", "Value" ], [ "Image size", "600x180 pt (1200x360 px @2x)" ], [ "Format", "PNG, TIF, or JPG" ], [ "Color space", "sRGB or P3" ], [ "Resolution", "72 DPI (minimum)" ] ] } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "Be aware of Game Center support on watchOS. While GameKit features and API are available for watchOS games, keep in mind that there’s no system-supported Game Center UI that you can invoke on watchOS. Instead, Game Center content for watchOS games appears on a connected iPhone." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Designing for games" }, { "type": "paragraph", "text": "Game controls" }, { "type": "paragraph", "text": "Apple Design Resources" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "GameKit" }, { "type": "paragraph", "text": "Creating activities for your game" }, { "type": "paragraph", "text": "Creating engaging challenges from leaderboards" }, { "type": "paragraph", "text": "Create games for Apple platforms" }, { "type": "paragraph", "text": "Game Porting Toolkit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Added guidance for new challenges and multiplayer activities, and considerations for the Apple Games app and Game Overlay. Updated guidance and specifications for activity preview images." ], [ "February 2, 2024", "Added links to developer guidance on using the access point and dashboard in a visionOS game." ], [ "September 12, 2023", "Added artwork for the iOS achievement layout." ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Accessing Game Center", "url": "/design/human-interface-guidelines/game-center#Accessing-Game-Center" }, { "title": "Integrating the access point", "url": "/design/human-interface-guidelines/game-center#Integrating-the-access-point" }, { "title": "Using custom UI", "url": "/design/human-interface-guidelines/game-center#Using-custom-UI" }, { "title": "Achievements", "url": "/design/human-interface-guidelines/game-center#Achievements" }, { "title": "Integrating achievements into your game", "url": "/design/human-interface-guidelines/game-center#Integrating-achievements-into-your-game" }, { "title": "Creating achievement images", "url": "/design/human-interface-guidelines/game-center#Creating-achievement-images" }, { "title": "Leaderboards", "url": "/design/human-interface-guidelines/game-center#Leaderboards" }, { "title": "Focus and selection", "url": "/design/human-interface-guidelines/focus-and-selection" }, { "title": "Challenges", "url": "/design/human-interface-guidelines/game-center#Challenges" }, { "title": "Multiplayer activities", "url": "/design/human-interface-guidelines/game-center#Multiplayer-activities" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/game-center#Platform-considerations" }, { "title": "tvOS", "url": "/design/human-interface-guidelines/game-center#tvOS" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/game-center#watchOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/game-center#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/game-center#Related" }, { "title": "Designing for games", "url": "/design/human-interface-guidelines/designing-for-games" }, { "title": "Game controls", "url": "/design/human-interface-guidelines/game-controls" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/game-center#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/game-center#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/game-center#Change-log" } ], "image_count": 0 }, { "title": "Generative AI", "url": "https://developer.apple.com/design/human-interface-guidelines/generative-ai", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Generative artificial intelligence uses machine learning models to create and transform text, images, and other content. Use it to offer novel, delightful features that help people express themselves creatively, communicate effectively, and complete tasks more easily. For instance, generative AI can enable people to edit text, create imaginative stories and images, or interact with a character in a game that uses AI-generated dialog." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Design your experience responsibly. Responsible AI is the intentional design and development of AI features that considers their direct and indirect impacts on people, systems, and society. With generative AI, it’s often easy to quickly prototype an exciting new feature for your app, yet challenging to create a robust experience that works in all real-world situations. Unlike classic programming, small changes to inputs (or even the same input, when given multiple times) often produce very different outcomes with generative AI. You also can’t always anticipate what requests people will make and how the AI will respond. Orient your design process around crafting AI experiences that are inclusive, designed with care, and protect privacy." }, { "type": "paragraph", "text": "Keep people in control. While AI can manipulate and create content, respect people’s agency and ensure they remain in charge of decision making and the overall experience. Honor their requests when in scope and the expected output is clear, and handle sensitive content carefully. Give them the ability to dismiss new content they don’t want, and revert or retry content transformations or other actions they don’t agree with. Clearly identify when and where you use AI." }, { "type": "paragraph", "text": "Ensure an inclusive experience for all. AI models learn from data and tend to favor the most common information. This may lead to harmful, unintended biases and stereotypes. Take extra care when designing your AI feature to consider how assumptions and personal attributes might impact the feature you have in mind. For example, if you generate images or descriptions of people, ask people to provide the information needed for the feature to work well rather than solely inferring personal or cultural characteristics. Seek clarity before making assumptions that may lead to common stereotypes, such as about gender identities or relationship types. Test your feature across a diverse set of people to identify and correct stereotypes, and ensure inclusive results. For guidance, see Inclusion and Accessibility." }, { "type": "paragraph", "text": "Design engaging and useful generative features. Generative AI is a powerful tool, but it’s not the right solution for every situation. Offer generative features when and where they provide clear and specific value, like time savings, improved communication, or enhanced creativity." }, { "type": "paragraph", "text": "Ensure a great experience even when generative features aren’t available or people opt not to use them. In some cases, generative AI may be essential to an experience, and there’s no reasonable non-AI substitute. In other cases, AI may play a complementary role that enhances your app’s core functionality, but isn’t critical for people achieving their goals. For example, Genmoji offers a fun way to create new, original emoji, but people can still use regular emoji too. The Apple Intelligence summarization feature makes catching up with notifications faster, but people can still read notifications without it. When possible, consider offering a non-AI fallback so people can always enjoy your app or game." } ] }, { "heading": "Transparency", "level": 2, "content": [ { "type": "paragraph", "text": "Communicate where your app uses AI. Letting people know when and where your app uses AI sets expectations and gives people the opportunity to knowingly choose to use an AI-powered feature. Never trick someone into thinking they’re interacting with or viewing content authored by a human if they’re actually interacting with AI. Ensure your approach to disclosure aligns with any regulations in the regions where you offer your app." }, { "type": "paragraph", "text": "Set clear expectations about what your AI-powered feature can and can’t do. Clarifying your experience’s capabilities and limitations helps people establish a mental model of your feature. For example, when you introduce a feature, you might offer a brief tutorial. For open-ended features like a search bar or generation prompt, consider offering curated suggestions that make it easy to get started. If your feature has known limitations, let people know up front, show them how to get good results, and explain why when inferior results occur. For guidance, see Limitations." } ] }, { "heading": "Privacy", "level": 2, "content": [ { "type": "paragraph", "text": "Prefer on-device processing. Depending on your needs, you may be able to get great responses using on-device models, which prevent people’s information from leaving the device. For example, you may choose to use the on-device models available through the Apple Foundation Models framework. On-device models may also respond quicker than server-based models, and are available even when the device is offline. Server-based models are usually good options in situations that need larger, powerful models that require more memory and power than is typically available on a person’s device. Always consider privacy and user experience tradeoffs when selecting a model type. If you’re using server-based processing, process as much information as you can locally first and minimize what’s shared. Make sure people know if their information may be sent to a server, can see what’s being shared, and understand what data may be stored off-device or even used for training." }, { "type": "paragraph", "text": "Ask permission before using personal information and usage data. Some interactions with an AI model may involve sensitive information, like personal details, messages, photos, and feature usage information. After obtaining permission, use the minimum data you need and always offer a clear way to opt out of its use. If you need sensitive data for model improvement or storage, get explicit permission and handle it with care. If you share data with third parties, understand their approach to privacy. Be aware that model outputs can inadvertently contain sensitive information. Note that apps for kids have stricter rules and laws around what data you can use. For guidance, see Requesting permission." }, { "type": "paragraph", "text": "Clearly disclose how your app and its model use and store personal information. People are more likely to be comfortable sharing data when they understand how it’s used. Empower people to make an informed decision about what data they share with your AI model. When asking for permission to use someone’s information, explain the benefits in a way that’s concise, specific, and easy to understand. Articulate whether your model uses personal information for training and improvement." } ] }, { "heading": "Models and datasets", "level": 2, "content": [ { "type": "paragraph", "text": "Thoughtfully evaluate model capabilities. There are different types of generative models, some of which possess general knowledge, while others are trained for specific tasks. It’s important to understand the capabilities of any model you consider. As early as you can, get a hands-on look at the models and data available to help orient your design. Keep in mind that some model types may be unavailable to people in certain situations due to factors like device compatibility, network access, and battery level. For example, the Foundation Models framework requires a compatible device with Apple Intelligence turned on." }, { "type": "paragraph", "text": "Be intentional when choosing or creating a dataset. Whether you’re training a model from scratch or customizing an existing model, the data you choose greatly impacts the model’s behavior. When you teach and evaluate your AI model, choose datasets that include a diverse range of subject matter representations. Learn where your data comes from and how it was gathered. Ensure you have relevant licenses for all data you don’t personally own, and offer appropriate choices when using people’s data. Most datasets gathered from the real world are imperfect, so allow time for testing and evaluation to proactively mitigate bias and misinformation that a model might learn and replicate." } ] }, { "heading": "Inputs", "level": 2, "content": [ { "type": "paragraph", "text": "Guide people on how to use your generative feature. Consider how to steer and educate people toward producing great results. One technique is to offer diverse, predefined example inputs that hint at what’s possible for a feature." }, { "type": "paragraph", "text": "Raise awareness about and minimize the chance of hallucinations. When a generative model is unsure how to respond to a request, it may produce content that seems plausible but is made up. These hallucinations can misinform people because the model may convincingly present the information as factual, even when it’s not. Generative models sometimes get details wrong, like dates of important events or information about people, so it’s important to clearly communicate that AI-generated content may contain errors. You can minimize the chance of hallucinations and limit their impact by carefully scoping what you ask a model to generate. Avoid requesting factual information unless you’re confident the model has access to verified and up-to-date information for the task. Avoid using AI-generated content in situations where a possible hallucination could misinform and harm someone." }, { "type": "paragraph", "text": "Consider consequences and get permission before performing destructive or potentially problematic tasks. Before performing a task, consider whether a mistake or the inability to reverse the action might cause more work or stress for people. Avoid automating destructive actions, like deleting photos, and actions that are hard to undo, like making a purchase on a person’s behalf. Generally, ask for confirmation before performing a significant action on someone’s behalf. Keep in mind that certain situations may be prohibited or have extra rules. Review and adhere to model-specific usage policies, as well as government and regulatory AI policy as it applies to each locale in which the generative features will be available." } ] }, { "heading": "Outputs", "level": 2, "content": [ { "type": "paragraph", "text": "Help people improve requests when blocked or undesirable results occur. Minimize scoped or blocked output by coaching people how to be more successful next time. For example, if prompted to generate harmful content, Image Playground says that it’s “Unable to use that description.” When possible, consider offering example requests that might lead to better results." }, { "type": "paragraph", "text": "Reduce unexpected and harmful outcomes with thoughtful design and thorough testing. People generally use apps with good intentions, but harmful outcomes can still arise from both accidental and purposeful misuse, and when responding to potentially sensitive topics. It may not be possible to mitigate every harmful scenario, but taking a proactive approach to identify risks, devise policies to address them, and evaluate features can help minimize the chance of misuse and harm. Consider ways people might interact with your feature and test those scenarios. Challenge your policies and expected use cases. See what happens when requests are out-of-scope, unrelated to the app experience you designed, and not well-represented by the model’s training data. Try requests that are poorly phrased, vague, or ambiguous; include personal, sensitive, or controversial topics; and encourage harmful or incorrect results. Use what you learn to improve your model, inform prevention, and respond thoughtfully." }, { "type": "paragraph", "text": "Strive to avoid replicating copyrighted content. Large AI models are trained using vast datasets from the internet and other sources. This means most generative models are familiar with and can unintentionally produce content similar to published work, including copyrighted content. You can reduce the likelihood of copyright infringement by building upon existing models that already protect against this, and by carefully curating inputs. For example, you might let people choose from a set of pre-approved prompts. You could also explicitly tell the model to avoid mimicking certain content or styles." }, { "type": "paragraph", "text": "Factor processing time into your design. Latency is how much time it takes for a model to produce an output. Non-generative models, such as people tracking in ARKit and the Vision machine learning framework, typically have low latency and are suitable to run in real-time on camera feeds. Generative models typically take longer to produce a result, so design a loading experience or generate in the background while a person uses another part of the app. For guidance, see Loading." }, { "type": "paragraph", "text": "Consider offering alternate versions of results. Depending on the design of your feature, it might work best to present a single result or multiple meaningfully different results from which people can choose. Offering people a choice can give them a greater sense of control and help bridge the gap between the model’s interpretation and what someone actually wants. For example, Image Playground can generate multiple images that represent a person, allowing someone to pick the one they prefer. For guidance, see Multiple options." } ] }, { "heading": "Continuous improvement", "level": 2, "content": [ { "type": "paragraph", "text": "Consider ways to improve your model over time. You may want to update your model to adapt to people’s behavior, respond to feedback, include new data, and leverage enhanced capabilities. You can make some improvements, such as updating a list of blocked words, frequently and independent of the app development cycle, and you can plan significant improvements and new features around regular app updates. Plan for fine-tuning, retesting, and prompt engineering when updating to a newer, more capable base model. If you train your own model, retrain with additional data and fine-tune to improve performance. Thoroughly test and refine all model updates to identify and correct unexpected behavior." }, { "type": "paragraph", "text": "Let people share feedback on outputs. Feedback can help you identify and respond to unexpected outcomes and new potential issues that arise despite thorough testing. Feedback also gives people a way to celebrate what they like best about your AI experience and report concerns when outputs don’t match their expectations. Establish trust by taking feedback seriously and resolving issues quickly. Always make providing feedback voluntary. Respect people’s time by placing a feedback affordance in a clear location that doesn’t interrupt the experience. Consider offering a quick and easy way to give positive and negative feedback, like simple thumbs-up and thumbs-down buttons. You might also offer a way to share detailed feedback for complicated issues. For guidance, see Explicit feedback and Implicit feedback." }, { "type": "paragraph", "text": "Design flexible, adaptable features. Generative AI is a rapidly advancing technology, and models and their resource needs are constantly evolving. Consider ways your app or game can adapt as capabilities and models improve. For example, you may want to separate your model from your user experience so you can swap out the model for other models over time. Lay a foundation that allows for future adjustments like this, while still offering the same great user experience." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Machine learning" }, { "type": "paragraph", "text": "Inclusion" }, { "type": "paragraph", "text": "Accessibility" }, { "type": "paragraph", "text": "Privacy" }, { "type": "paragraph", "text": "Loading" }, { "type": "paragraph", "text": "Acceptable Use Requirements for the Foundation Models Framework" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Intelligence and machine learning" }, { "type": "paragraph", "text": "Foundation Models" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "New page." ] ] } ] } ], "platforms": [], "related": [ { "title": "machine learning", "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/generative-ai#Best-practices" }, { "title": "Inclusion", "url": "/design/human-interface-guidelines/inclusion" }, { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Transparency", "url": "/design/human-interface-guidelines/generative-ai#Transparency" }, { "title": "Limitations", "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Limitations" }, { "title": "Privacy", "url": "/design/human-interface-guidelines/generative-ai#Privacy" }, { "title": "Requesting permission", "url": "https://developer.apple.com/design/human-interface-guidelines/privacy#Requesting-permission" }, { "title": "Models and datasets", "url": "/design/human-interface-guidelines/generative-ai#Models-and-datasets" }, { "title": "Inputs", "url": "/design/human-interface-guidelines/generative-ai#Inputs" }, { "title": "Outputs", "url": "/design/human-interface-guidelines/generative-ai#Outputs" }, { "title": "Loading", "url": "/design/human-interface-guidelines/loading" }, { "title": "Multiple options", "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Multiple-options" }, { "title": "Continuous improvement", "url": "/design/human-interface-guidelines/generative-ai#Continuous-improvement" }, { "title": "Explicit feedback", "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Explicit-feedback" }, { "title": "Implicit feedback", "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning#Implicit-feedback" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/generative-ai#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/generative-ai#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/generative-ai#Related" }, { "title": "Machine learning", "url": "/design/human-interface-guidelines/machine-learning" }, { "title": "Privacy", "url": "/design/human-interface-guidelines/privacy" }, { "title": "Videos", "url": "/design/human-interface-guidelines/generative-ai#Videos" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/generative-ai#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/generative-ai#Change-log" } ], "image_count": 0 }, { "title": "HealthKit", "url": "https://developer.apple.com/design/human-interface-guidelines/healthkit", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "When you support HealthKit in your app, you can ask people for permission to access and update their health information." }, { "type": "important", "text": "ImportantIf your app doesn’t provide health and fitness functionality, don’t request access to people’s private health data." }, { "type": "paragraph", "text": "For example, a nutrition app might ask for permission to retrieve people’s weight and activity data, so it can define calorie consumption goals and make dietary recommendations. In this scenario, the nutrition app could also send data — such as the calories that people log — to HealthKit, which can include the data in its global progress metrics." }, { "type": "paragraph", "text": "For developer guidance, see HealthKit." } ] }, { "heading": "Privacy protection", "level": 2, "content": [ { "type": "paragraph", "text": "You must request permission to access people’s data, and you must take all necessary steps to protect that data. After you receive permission, it’s essential to maintain people’s trust by clearly showing them how you use their data. For developer guidance, see Protecting user privacy." }, { "type": "paragraph", "text": "Provide a coherent privacy policy. During the app submission process, you must provide a URL to a clearly stated privacy policy, so that people can view the policy when they click the link in the App Store page for your app. For developer guidance, see App Information > App Store Connect Help." }, { "type": "paragraph", "text": "Request access to health data only when you need it. It makes sense to request access to weight information when people log their weight, for example, but not immediately after your app launches. When your request is clearly related to the current context, you help people understand your app’s intentions. Also, people can change the permissions they grant, so your app needs to make a request every time it needs access. For developer guidance, see requestAuthorization(toShare:read:completion:)." }, { "type": "paragraph", "text": "Clarify your app’s intent by adding descriptive messages to the standard permission screen. People expect to see the system-provided permission screen when asked to approve access to health data. Write a few succinct sentences that explain why you need the information and how people can benefit from sharing it with your app. Avoid adding custom screens that replicate the standard permission screen’s behavior or content." }, { "type": "paragraph", "text": "Manage health data sharing solely through the system’s privacy settings. People expect to globally manage access to their health information in Settings > Privacy. Don’t confuse people by building additional screens in your app that affect the flow of health data." } ] }, { "heading": "Activity rings", "level": 2, "content": [ { "type": "paragraph", "text": "You can enhance your app’s health and wellness offerings by displaying the Activity ring element to show people’s progress toward their Move, Exercise, and Stand goals. The Activity app defines the position and color of each ring, so people are familiar with the element and understand what it means." }, { "type": "paragraph", "text": "Use Activity rings for Move, Exercise, and Stand information only. Activity rings consistently represent progress in these specific areas. Don’t attempt to replicate or modify Activity rings for other purposes or to display other types of data. Never show Move, Exercise, and Stand progress in another ring-like element." }, { "type": "paragraph", "text": "Use Activity rings to show progress for a single person. Never use Activity rings to represent data for more than one person, and make sure it’s obvious whose progress is shown, such as by using a label, a photo, or an avatar." }, { "type": "paragraph", "text": "Don’t use Activity rings for ornamentation. Activity rings provide information to people; they don’t merely embellish your app’s design. Never display Activity rings in labels or background graphics." }, { "type": "paragraph", "text": "Don’t use Activity rings for branding. Use Activity rings strictly to display Activity progress in your app. Never use Activity rings in your app’s icon or marketing materials." }, { "type": "paragraph", "text": "Maintain Activity ring and background colors. For a consistent user experience, the visual appearance of Activity rings must always be the same, regardless of the context in which they appear. Never change the look of the rings or background by using filters, changing colors, or modifying opacity. Instead, design the surrounding interface to blend with the rings. For example, enclose the rings within a circle. Always scale the rings appropriately so they don’t seem disconnected or out of place." }, { "type": "paragraph", "text": "Maintain Activity ring margins. An Activity ring element must include a minimum outer margin of no less than the distance between rings. Never allow other elements to crop, obstruct, or encroach upon this margin or the rings themselves. To display an Activity ring element within a circle, adjust the corner radius of the enclosing view rather than applying a circular mask." }, { "type": "paragraph", "text": "Differentiate other ring-like elements from Activity rings. Mixing different ring styles can lead to a visually confusing interface. If you must include other rings, use padding, lines, or labels to separate them from Activity rings. Color and scale can also help provide visual separation." }, { "type": "paragraph", "text": "Provide app-specific information only in Activity notifications. The system already delivers Move, Exercise, and Stand progress updates. Don’t repeat this same information, and never show an Activity ring element in your app’s notifications. It’s fine to reference Activity progress in a notification, but do so in a way that’s unique to your app and doesn’t replicate the same information provided by the system." }, { "type": "paragraph", "text": "For developer guidance, see HKActivityRingView." } ] }, { "heading": "Apple Health icon", "level": 2, "content": [ { "type": "paragraph", "text": "The Apple Health icon shows that an app works with HealthKit and the Health app. The following guidelines help you use the icon correctly. To learn how to refer to HealthKit and the Health app in copy and UI text, see Editorial guidelines; to learn about using the “Works with Apple Health” badge in your marketing communications, see Works with Apple Health." }, { "type": "paragraph", "text": "Use only the Apple-provided icon. Don’t create your own Apple Health icon design or attempt to mimic any Apple-provided designs. Download the Apple Health app icon from Apple Design Resources." }, { "type": "paragraph", "text": "Display the name Apple Health close to the Apple Health icon. Displaying both elements near each other reminds people that the icon represents the Health app." }, { "type": "paragraph", "text": "Display the Apple Health icon consistently with other health-related app icons. In a view that contains other app icons, make the Apple Health icon no smaller than other icons." }, { "type": "paragraph", "text": "Don’t use the Apple Health icon as a button. Use the icon only to indicate compatibility with the Health app." }, { "type": "paragraph", "text": "Don’t alter the appearance of the Apple Health icon. Don’t mask the icon to change its corner radius or present it in a circular shape. Don’t add embellishments like borders, color overlays, gradients, shadows, or other visual effects." }, { "type": "paragraph", "text": "Maintain a minimum clear space around the Apple Health icon of 1/10 of its height. Don’t composite the icon onto another graphic element." }, { "type": "paragraph", "text": "Don’t use the Apple Health icon within text or as a replacement for the terms Health, Apple Health, or HealthKit. See Editorial guidelines to learn how to properly reference the Health app and HealthKit in text." }, { "type": "paragraph", "text": "Don’t display Health app images or screenshots. Like all Apple images, these designs are copyrighted and can’t appear in your app or marketing materials. You can include an Activity ring element in your app to display Move, Exercise, and Stand progress; for guidance, see Activity rings." } ] }, { "heading": "Editorial guidelines", "level": 2, "content": [ { "type": "paragraph", "text": "Refer to the Health app as Apple Health or the Apple Health app. In your app and marketing text, using Apple Health adds clarity." }, { "type": "paragraph", "text": "Don’t use the term HealthKit. HealthKit is a developer-facing term that names the framework your app uses to access health data. If you need to explain to people how your app works with their data, use the term the Apple Health app. For example, you might say that your app “works with the Apple Health app” or “uses data from the Apple Health app.”" }, { "type": "paragraph", "text": "Use correct capitalization when using the term Apple Health. Apple Health is two words, with an uppercase A and uppercase H, followed by lowercase letters. You can display Apple Health entirely in uppercase only when you need to conform to an established typographic interface style, such as in an app that capitalizes all text." }, { "type": "paragraph", "text": "Use the system-provided translation of Health to avoid confusing people. It’s best to refer to the Apple Health app using the translation that people view on their device." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, or watchOS. Not supported in macOS, tvOS, or visionOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Works with Apple Health" }, { "type": "paragraph", "text": "Activity rings" }, { "type": "paragraph", "text": "Apple Design Resources" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "HealthKit" }, { "type": "paragraph", "text": "Protecting user privacy — HealthKit" } ] } ], "platforms": [], "related": [ { "title": "Privacy protection", "url": "/design/human-interface-guidelines/healthkit#Privacy-protection" }, { "title": "Activity rings", "url": "/design/human-interface-guidelines/healthkit#Activity-rings" }, { "title": "Apple Health icon", "url": "/design/human-interface-guidelines/healthkit#Apple-Health-icon" }, { "title": "Editorial guidelines", "url": "/design/human-interface-guidelines/healthkit#Editorial-guidelines" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/healthkit#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/healthkit#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/healthkit#Related" }, { "title": "Activity rings", "url": "/design/human-interface-guidelines/activity-rings" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/healthkit#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/healthkit#Videos" } ], "image_count": 0 }, { "title": "HomeKit", "url": "https://developer.apple.com/design/human-interface-guidelines/homekit", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "In iOS, the Home app also lets people manage and configure accessories." }, { "type": "paragraph", "text": "Your iOS, tvOS, or watchOS app can integrate with HomeKit (and by extension the Home app) to provide a custom or accessory-specific experience. For example, you can:" }, { "type": "list", "items": [ "Help people set up, name, and organize their accessories", "Allow fine-grained accessory configuration and control", "Provide access to custom accessory features", "Show people how to create powerful, hands-free automations", "Provide support" ] }, { "type": "paragraph", "text": "For developer guidance, see HomeKit. If you’re an MFi licensee, visit the MFi portal for guidance on naming and messaging for accessory packaging." } ] }, { "heading": "Terminology and layout", "level": 2, "content": [ { "type": "paragraph", "text": "HomeKit models the home as a hierarchy of objects and defines a vocabulary of terms that refer to them. The Home app uses the HomeKit object model and terminology to give people intuitive control of accessories by voice, app, and automation." }, { "type": "paragraph", "text": "It’s crucial for your app to use the terminology and object model that HomeKit defines, so that you can reinforce people’s understanding and make home automation feel approachable." }, { "type": "paragraph", "text": "In the HomeKit model, the home object is the root of a hierarchy that contains all other objects, such as rooms, accessories, and zones. When there’s more than one home, each home is the root of a different hierarchy." }, { "type": "paragraph", "text": "Acknowledge the hierarchical model that HomeKit uses. Even if your app doesn’t organize accessories by rooms and zones in its UI, it’s useful to reference the HomeKit model when helping people set up or control their accessories. People need to know where accessories are located so they can use Siri and HomePod to control them by speaking commands like “Siri, turn on the lights upstairs,” or “It’s dark in here.” For more guidance, see Siri interactions." }, { "type": "paragraph", "text": "Make it easy for people to find an accessory’s related HomeKit details. If your app’s organization is based on accessories, don’t hide other HomeKit information, such as an accessory’s zone or room, in a hard-to-discover settings screen. Instead, consider making the related HomeKit information easily available in an accessory detail view." }, { "type": "paragraph", "text": "Recognize that people can have more than one home. Even if your app doesn’t support the concept of multiple homes per user, consider providing the relevant home information in an accessory detail view." }, { "type": "paragraph", "text": "Don’t present duplicate home settings. If your app has a different perspective on the organization of a home, don’t confuse people by asking them to set up all or parts of their homes again or by showing a duplicate settings view. Always defer to the settings people made in the Home app and find an intuitive way to present these details in your UI." } ] }, { "heading": "Homes", "level": 3, "content": [ { "type": "paragraph", "text": "HomeKit uses the term home to represent a physical home, office, or other location of relevance to people. One person might have multiple homes." } ] }, { "heading": "Rooms", "level": 3, "content": [ { "type": "paragraph", "text": "A room represents a physical room in a home. Rooms don’t have attributes like size or location; they’re simply names that have meaning to people, such as Bedroom or Office. When people assign accessories to a room, they can use voice commands like “Siri, turn on all the lights except the bedroom,” or “Siri, turn on the kitchen and hallway lights.”" } ] }, { "heading": "Accessories, services, and characteristics", "level": 3, "content": [ { "type": "paragraph", "text": "The term accessory represents a physical, connected home accessory, like a ceiling fan, lamp, lock, or camera. HomeKit uses category to represent a type of accessory, such as thermostat, fan, or light. Typically, an accessory manufacturer assigns each accessory to a category, but your app can help people make this assignment if necessary. For example, a switch that’s connected to a fan or a lamp needs to be assigned to the same category as the accessory it controls." }, { "type": "paragraph", "text": "A controllable feature of an accessory, such as the switch on a connected light, is known as a service. Some accessories offer multiple services. For example, a connected garage door might let people control the light and the door separately, or a connected outlet might support separate control of the top outlet and the bottom outlet. Apps don’t use the word service in the UI; instead, they use names that describe the service, such as garage door opener and ceiling fan light. When people use Siri to control the accessories in their homes, they speak the service name, not the accessory name. For more guidance on naming, see Help people choose useful names." }, { "type": "paragraph", "text": "A characteristic is a controllable attribute of a service. For example, in a ceiling fan, the fan service might have a speed characteristic and the light service might have a brightness characteristic. Apps don’t use the word characteristic in the UI; instead, they use terms that describe the attribute, such as speed and brightness." }, { "type": "paragraph", "text": "A service group represents a group of accessory services that someone might want to control as a unit. For example, if there’s a floor lamp and two table lamps in one corner of a room, people might assign all three services to a service group named reading lamps. Doing so would let people use the reading lamps service group to control these three lights independently of all other lights in the room." } ] }, { "heading": "Actions and scenes", "level": 3, "content": [ { "type": "paragraph", "text": "The term action refers to the changing of a service’s characteristic, such as adjusting the speed of a fan or the brightness of a light. People and automation can initiate actions." }, { "type": "paragraph", "text": "A scene is a group of actions that control one or more services in one or more accessories. For example, people might create a Movie Time scene that lowers the shades and dims the lights in the living room, or a Good Morning scene that turns on the lights, raises the shades, and starts the coffee maker in the kitchen." }, { "type": "tip", "text": "TipThe HomeKit API uses the term action set instead of scene. In your app’s UI, always use the term scene." } ] }, { "heading": "Automations", "level": 3, "content": [ { "type": "paragraph", "text": "Automations cause accessories to react to certain situations, such as when a person’s location changes, a particular time of day occurs, another accessory turns on or off, or a sensor detects something. For example, an automation could turn on the house lights at sunset or when people arrive home." } ] }, { "heading": "Zones", "level": 3, "content": [ { "type": "paragraph", "text": "A zone represents an area in the home that contains multiple rooms, such as upstairs or downstairs. Setting up a zone is optional, but doing so lets people control multiple accessories at one time. For example, assigning all downstairs lights to a zone named downstairs lets people use voice commands like “Siri, turn off all the lights downstairs.”" } ] }, { "heading": "Setup", "level": 2, "content": [ { "type": "paragraph", "text": "Use the system-provided setup flow to give people a familiar experience. The HomeKit setup flow works more quickly than traditional setup flows because it lets people name accessories, join networks, pair with HomeKit, assign room and service categories, and designate favorites in just a few steps. Using the system-provided setup flow lets you concentrate on promoting the custom functionality that makes your accessory unique. For developer guidance, see performAccessorySetup(using:completionHandler:)." }, { "type": "paragraph", "text": "Provide context to explain why you need access to people’s Home data. Create a purpose string with a phrase that describes why you’re asking for permission to access data, such as “Lets you control this accessory with the Apple Home app and Siri across your Apple devices.”" }, { "type": "paragraph", "text": "Don’t require people to create an account or supply personal information. Instead, defer to HomeKit for any information you might need. If your app provides additional services that require an account, such as cloud services, make account setup optional and wait until after initial HomeKit setup to offer it." }, { "type": "paragraph", "text": "Honor people’s setup choices. When people choose to use HomeKit to set up your accessory, don’t force them to set up other platforms during the HomeKit setup flow. A cross-platform setup experience prevents people from using the accessory right away and can cause confusion by presenting too many ways to control the accessory." }, { "type": "paragraph", "text": "Carefully consider how and when to provide a custom accessory setup experience. Always begin by presenting the system-provided setup flow. Then, after the accessory’s basic functionality is available, offer a custom post-setup experience that highlights the unique features of your accessory and helps people get the most out of it. For example, a light manufacturer’s app could help people create personalized light scenes in their homes using key colors scanned in from photos in their library." } ] }, { "heading": "Help people choose useful names", "level": 3, "content": [ { "type": "paragraph", "text": "Suggest service names that suit your accessory. If your app detects when someone creates a suboptimal name for Siri voice controls, recommend alternatives that you know will work well for most people. Never suggest company names or model numbers for use as service names." }, { "type": "paragraph", "text": "Check that the names people provide follow HomeKit naming rules. If your app lets people rename services, make sure that the new names follow the rules. (The system-provided setup flow automatically checks the original names.) If people enter a name that breaks one or more rules, briefly explain the problem and suggest some alternative names that work. Here are the rules:" }, { "type": "list", "items": [ "Use only alphanumeric, space, and apostrophe characters.", "Start and end with an alphabetic or numeric character.", "Don’t include emojis." ] }, { "type": "table", "rows": [ [ "", "Example service names" ], [ "", "Reading lamp" ], [ "", "📚 lamp" ], [ "", "2nd garage door" ], [ "", "#2 garage door" ] ] }, { "type": "paragraph", "text": "Help people avoid creating names that include location information. Although it’s natural for someone to use “kitchen light” to name a light in the kitchen, including the room name in the service name can lead to unpredictable results when controlling the accessory by voice. Your app can detect service names that duplicate location information and help people fix them. For example, you might present a post-setup experience that removes the room or zone from a service name and encourages people to assign the accessory to that room or zone instead." } ] }, { "heading": "Siri interactions", "level": 2, "content": [ { "type": "paragraph", "text": "HomeKit supports powerful, hands-free control using voice commands. You can help people use Siri to interact with accessories, services, and zones in their home quickly and efficiently." }, { "type": "paragraph", "text": "Present example voice commands to demonstrate using Siri to control accessories during setup. As soon as people complete the setup of a new accessory, consider using the service name they chose in a few example Siri phrases and encourage people to try them out." }, { "type": "paragraph", "text": "After setup, consider teaching people about more complex Siri commands. People might not be aware of the broad range of natural language phrases they can use with Siri and HomePod to control their accessories. After setup is complete, find useful places throughout your app to help people learn about these types of commands. For example, in a scene detail view, you could tell people, You can say “Hey Siri, set ‘Movie Time.’”" }, { "type": "paragraph", "text": "In addition to recognizing the names of homes, rooms, zones, services, and scenes, Siri can also use information such as accessory category and characteristic to identify a service. For example, when people use terms like brighter or dim, Siri recognizes that they’re referring to a service that has a brightness characteristic, even if they don’t speak the name of the service." }, { "type": "paragraph", "text": "To illustrate the power and flexibility of Siri commands, here are some examples of the types of phrases that people could use to control their accessories." }, { "type": "table", "rows": [ [ "Phrase", "Siri understands" ], [ "“Turn on the floor lamp”", "Service (floor lamp)" ], [ "“Show me the entryway camera”", "Service (entryway camera)" ], [ "“Turn on the light”", "Accessory category (light)" ], [ "“Turn off the living room light”", "Room (living room)" ], [ "Accessory category (light)" ], [ "“Make the living room a little bit brighter”", "Room (living room)" ], [ "Accessory category (implied)" ], [ "Brightness characteristic (brighter)" ], [ "“Turn on the recessed lights”", "Service group (recessed lights)" ], [ "“Turn off the lights upstairs”", "Accessory category (lights)" ], [ "Zone (upstairs)" ], [ "“Dim the lights in the bedroom and nursery”", "Accessory category (lights)" ], [ "Brightness characteristic (dim)" ], [ "Rooms (bedroom, nursery)" ], [ "“Run Good night”", "Scene (Good night)" ], [ "“Is someone in the living room?”", "Accessory category (implied)" ], [ "Occupancy detection characteristic (implied)" ], [ "“Is my security system tripped?”", "Accessory category (security system)" ], [ "“Did I leave the garage door open?”", "Accessory category (garage door)" ], [ "Open characteristic (open)" ], [ "“Did I forget to turn off the lights in the Tahoe House?”", "Accessory category (lights)" ], [ "Home (Tahoe House)" ], [ "“It’s dark in here”", "Current home (here)" ], [ "Current room (via HomePod)" ], [ "Accessory category (implied)" ] ] }, { "type": "paragraph", "text": "Recommend that people create zones and service groups, if they make sense for your accessory. If people might benefit from using context-specific voice commands to control your accessory, suggest these types of interactions and help people set them up. For example, if you provide an accessory such as a light, switch, or thermostat, you could suggest setting up a zone named “upstairs” or a service group named “media center” to support commands like “Siri, turn off the upstairs lights,” or “Siri, activate the media center.”" }, { "type": "paragraph", "text": "Offer shortcuts only for accessory-specific functionality that HomeKit doesn’t support. HomeKit lets people use ordinary (or natural) language to control accessories without requiring any additional configuration, so you avoid confusing people by offering shortcuts that duplicate HomeKit functionality. Instead, consider offering shortcuts for complementary functionality that your app provides. For example, if people often want to order filters for an air conditioner that you support, you might offer a shortcut like “Order AC filters.” To learn how to provide phrases that people can use for shortcuts, see Shortcuts and suggestions." }, { "type": "paragraph", "text": "If your app supports both HomeKit and shortcuts, help people understand the difference between these types of voice control. People can get confused if they’re presented with multiple methods of voice control. Be sure you clearly indicate what’s possible with shortcuts, and never encourage people to create a shortcut for a scene or action that HomeKit already supports." } ] }, { "heading": "Custom functionality", "level": 2, "content": [ { "type": "paragraph", "text": "Your app is a great place to help people appreciate the unique functionality of your accessory. For example, an app for a light that displays different colors could help people create HomeKit scenes using colors imported from their photos." }, { "type": "paragraph", "text": "Be clear about what people can do in your app and when they might want to use the Home app. For example, if your app supports only lights, consider encouraging people to create a “Movie Time” scene that not only dims the lights, but also closes the shades, and turns on the TV to a specific input. To do this, first guide people to set up a scene that includes only your accessory’s actions — in this scenario, dimming the lights. Then, your app can suggest that people open the Home app to add their HomeKit-compatible shades and TV to the scene you helped them create. For guidance on how to refer to the Home app, see Referring to HomeKit." }, { "type": "paragraph", "text": "Defer to HomeKit if your database differs from the HomeKit database. Give people a seamless experience by automatically reflecting changes made in the Home app or in other third-party HomeKit apps. If you must ask people to manage conflicts in your app, present the conflict visually so that they have a clear picture of the choice they need to confirm. For example, if someone changes an accessory’s service name in the Home app, your app can detect this change and could show both names side by side to confirm that the person wants to use the new name in your app, too." }, { "type": "paragraph", "text": "Ask permission to update the HomeKit database when people make changes in your app. You don’t want to surprise people by changing something in the Home app, so it’s essential to get permission or an indication of intent before you write to the database. In particular, never overwrite HomeKit database settings without a person’s explicit direction." } ] }, { "heading": "Cameras", "level": 3, "content": [ { "type": "paragraph", "text": "Your app can display still images or streaming video from a connected HomeKit IP camera." }, { "type": "paragraph", "text": "Don’t block camera images. It’s fine to supplement the camera’s content with useful features, such as an alert calling attention to potentially interesting activity. However, avoid covering portions of the camera’s images with other content." }, { "type": "paragraph", "text": "Show a microphone button only if the camera supports bidirectional audio. A nonfunctioning microphone button takes up valuable display space in your app and risks confusing people." } ] }, { "heading": "Using HomeKit icons", "level": 2, "content": [ { "type": "paragraph", "text": "Use the HomeKit icon in setup or instructional communications related to HomeKit technology." }, { "type": "paragraph", "text": "In addition, you can use the Apple Home app icon when referencing the Apple Home app or in a button that opens the Apple Home app product page in the App Store." }, { "type": "paragraph", "text": "Use only Apple-provided icons. Don’t create your own HomeKit or Home app icon design or attempt to mimic the Apple-provided designs. Download HomeKit icons in Resources." } ] }, { "heading": "Styles", "level": 3, "content": [ { "type": "paragraph", "text": "You have several options for displaying the HomeKit icon." } ] }, { "heading": "Black HomeKit icon", "level": 4, "content": [ { "type": "paragraph", "text": "Use the HomeKit icon on white or light backgrounds when other technology icons appear in black." } ] }, { "heading": "White HomeKit icon", "level": 4, "content": [ { "type": "paragraph", "text": "Use the HomeKit icon on black or dark backgrounds when other technology icons appear in white." } ] }, { "heading": "Custom color HomeKit icon", "level": 4, "content": [ { "type": "paragraph", "text": "Use a custom color when other technology icons appear in the same color." }, { "type": "paragraph", "text": "Position the HomeKit icon consistently with other technology icons. When other technology icons are contained within shapes, treat the HomeKit icon in the same manner." }, { "type": "paragraph", "text": "Use the HomeKit icon noninteractively. Don’t use the icon and the name HomeKit in custom interactive elements or buttons. You can use the Apple Home app icon to open the app’s product page in the App Store." }, { "type": "paragraph", "text": "Don’t use the HomeKit icon within text or as a replacement for the word HomeKit. See Referring to HomeKit to learn how to properly reference HomeKit in text." }, { "type": "paragraph", "text": "Pair the icon with the name HomeKit correctly. You can show the name below or beside the icon if other technologies are referenced in this way. Use the same font that’s used on the rest of your layout. For related guidance, see Referring to HomeKit." }, { "type": "paragraph", "text": "Using the icon and name in setup or instructional content" }, { "type": "paragraph", "text": "Using the icon and name referencing the Apple Home app" } ] }, { "heading": "Referring to HomeKit", "level": 2, "content": [ { "type": "paragraph", "text": "Emphasize your app over HomeKit. Make references to HomeKit or Apple Home less prominent than your app name or main identity." }, { "type": "paragraph", "text": "Adhere to Apple’s trademark guidelines. Apple trademarks can’t appear in your app name or images. In text, use Apple product names exactly as shown on the Apple Trademark List." }, { "type": "list", "items": [ "Use Apple product names in singular form only; do not make Apple product names possessive.", "Don’t translate Apple, Apple Home, HomeKit, or any other Apple trademark.", "Don’t use category descriptors. For example, say iPad, not tablet.", "Don’t indicate any kind of sponsorship, partnership, or endorsement from Apple.", "Attribute Apple, HomeKit, and all other Apple trademarks with the correct credit lines wherever legal information appears within your app.", "Refer to Apple devices and operating systems only in technical specifications or compatibility descriptions." ] }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Use HomeKit to turn on your lights from your iPhone or iPad." ], [ "", "Use HomeKit to turn on your lights from your iOS devices." ] ] }, { "type": "paragraph", "text": "See Guidelines for Using Apple Trademarks." } ] }, { "heading": "Referencing HomeKit and the Home app", "level": 3, "content": [ { "type": "paragraph", "text": "Use correct capitalization when using the term HomeKit. HomeKit is one word, with an uppercase H and uppercase K, followed by lowercase letters. Apple Home is two words, with an uppercase A and uppercase H, followed by lowercase letters. If your layout displays only all-uppercase designations, HomeKit or Apple Home can be typeset in all uppercase to match the style of the rest of the layout." }, { "type": "paragraph", "text": "Don’t use the name HomeKit as a descriptor. Instead use terms like works with, use, supports, or compatible." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "[Brand] lightbulbs work with HomeKit." ], [ "", "HomeKit-enabled thermostat." ], [ "", "You can use HomeKit with [App Name]." ], [ "", "HomeKit lightbulbs." ] ] }, { "type": "paragraph", "text": "Don’t suggest that HomeKit is performing an action or function." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Back door is unlocked with HomeKit." ], [ "", "HomeKit unlocked the back door." ] ] }, { "type": "paragraph", "text": "Use the name Apple with the name HomeKit, if desired." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Compatible with Apple HomeKit." ] ] }, { "type": "paragraph", "text": "Use the name HomeKit for setup, configuration, and instructions, if desired." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Open HomeKit settings." ] ] }, { "type": "paragraph", "text": "Use the app name Apple Home whenever referring specifically to the app. On the first mention of the app in body copy, use the complete name Apple Home. Subsequent mentions can refer to the Home app." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Open the Apple Home app." ], [ "", "Open the Apple Home app. Your accessory and room will now appear in the Home app." ], [ "", "Open Home." ] ] } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Design Resources" }, { "type": "paragraph", "text": "Guidelines for Using Apple Trademarks and Copyrights" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "HomeKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Terminology and layout", "url": "/design/human-interface-guidelines/homekit#Terminology-and-layout" }, { "title": "home", "url": "/design/human-interface-guidelines/homekit#Homes" }, { "title": "rooms", "url": "/design/human-interface-guidelines/homekit#Rooms" }, { "title": "accessories", "url": "/design/human-interface-guidelines/homekit#Accessories-services-and-characteristics" }, { "title": "zones", "url": "/design/human-interface-guidelines/homekit#Zones" }, { "title": "Siri interactions", "url": "/design/human-interface-guidelines/homekit#Siri-interactions" }, { "title": "Help people choose useful names", "url": "/design/human-interface-guidelines/homekit#Help-people-choose-useful-names" }, { "title": "Actions and scenes", "url": "/design/human-interface-guidelines/homekit#Actions-and-scenes" }, { "title": "Automations", "url": "/design/human-interface-guidelines/homekit#Automations" }, { "title": "Setup", "url": "/design/human-interface-guidelines/homekit#Setup" }, { "title": "Shortcuts and suggestions", "url": "/design/human-interface-guidelines/siri#Shortcuts-and-suggestions" }, { "title": "Custom functionality", "url": "/design/human-interface-guidelines/homekit#Custom-functionality" }, { "title": "Referring to HomeKit", "url": "/design/human-interface-guidelines/homekit#Referring-to-HomeKit" }, { "title": "Cameras", "url": "/design/human-interface-guidelines/homekit#Cameras" }, { "title": "Using HomeKit icons", "url": "/design/human-interface-guidelines/homekit#Using-HomeKit-icons" }, { "title": "Styles", "url": "/design/human-interface-guidelines/homekit#Styles" }, { "title": "Black HomeKit icon", "url": "/design/human-interface-guidelines/homekit#Black-HomeKit-icon" }, { "title": "White HomeKit icon", "url": "/design/human-interface-guidelines/homekit#White-HomeKit-icon" }, { "title": "Custom color HomeKit icon", "url": "/design/human-interface-guidelines/homekit#Custom-color-HomeKit-icon" }, { "title": "Referencing HomeKit and the Home app", "url": "/design/human-interface-guidelines/homekit#Referencing-HomeKit-and-the-Home-app" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/homekit#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/homekit#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/homekit#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/homekit#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/homekit#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/homekit#Change-log" } ], "image_count": 0 }, { "title": "ID Verifier", "url": "https://developer.apple.com/design/human-interface-guidelines/id-verifier", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Beginning in iOS 17, you can integrate ID Verifier into your app, letting iPhone read ISO18013-5 compliant mobile IDs and helping you support in-person ID verification. For example, personnel at a concert venue can use your app on iPhone to verify customers’ ages." }, { "type": "paragraph", "text": "Using ID Verifier has advantages for both customers and organizations." }, { "type": "list", "items": [ "Customers only present the minimum data needed to prove their age or identity, without handing over their ID card or showing their device.", "Apple provides the key components of the certificate issuance, management, and validation process, simplifying app development and enabling a consistent and trusted ID verification experience." ] }, { "type": "paragraph", "text": "Depending on the needs of your app, you can use ID Verifier to make the following types of requests:" }, { "type": "list", "items": [ "Display Only request. Use a Display Only request to display data — such as a person’s name or age alongside their photo portrait — within system-provided UI on the requester’s iPhone, so the requester can visually confirm the person’s identity. When you make a Display Only request, the customer’s data remains within the system-provided UI and isn’t transmitted to your app. For developer guidance, see MobileDriversLicenseDisplayRequest.", "Data Transfer request. Use a Data Transfer request only when you have a legal verification requirement and you need to store or process information like a person’s address or date of birth. You must request an additional entitlement to make a Data Transfer request. To learn more, see Get started with ID Verifier; for developer guidance, see MobileDriversLicenseDataRequest and MobileDriversLicenseRawDataRequest." ] } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Ask only for the data you need. People may lose trust in the experience if you ask for more data than you need to complete the current verification. For example, if you need to ensure that a customer is at least a minimum age, use a request that specifies an age threshold; avoid requesting the customer’s current age or birth date. For developer guidance, see ageAtLeast(_:)." }, { "type": "paragraph", "text": "If your app qualifies for Apple Business Register, register for ID Verifier to ensure that people can view essential information about your organization when you make a request. Registering for ID Verifier with Apple Business Register lets you provide your official organization name and logo for the system to display on customers’ devices as part of the ID verification UI. To learn if your app qualifies and how to register, see Apple Business Register." }, { "type": "paragraph", "text": "Provide a button that initiates the verification process. Use a label like Verify Age in a button that performs a simple age check or Verify Identity for a more detailed identity data request. Avoid including a symbol that specifies a particular type of communication, like NFC or QR codes. Never include the Apple logo in any button label." }, { "type": "table", "rows": [ [ "Button type", "Example usage" ], [ "", "An app that checks whether people are old enough to attend an event or access a venue, like a concert hall." ], [ "", "An app that verifies whether specific identity information matches expected values, such as name and birth date when picking up a rental car." ] ] }, { "type": "paragraph", "text": "In a Display Only request, help the person using your app provide feedback on the visual confirmation they perform. For example, when the reader displays the customer’s portrait, you might provide buttons labeled Matches Person and Doesn’t Match Person so your app can receive an approved or rejected value as part of the response." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS. Not supported in iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Business Register" }, { "type": "paragraph", "text": "IDs in Wallet" }, { "type": "paragraph", "text": "Identity verification" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Adopting the Verifier API in your iPhone app — ProximityReader" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 12, 2023", "New page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/id-verifier#Best-practices" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/id-verifier#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/id-verifier#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/id-verifier#Related" }, { "title": "Identity verification", "url": "/design/human-interface-guidelines/wallet#Identity-verification" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/id-verifier#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/id-verifier#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/id-verifier#Change-log" } ], "image_count": 0 }, { "title": "In-app purchase", "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "You can also promote and offer in-app purchases directly through the App Store. For developer guidance, see In-App Purchase." }, { "type": "tip", "text": "TipIn-app purchase and Apple Pay are different technologies that support different use cases. Use in-app purchase to sell virtual goods in your app, such as premium content for your app and subscriptions for digital content. Use Apple Pay in your app to sell physical goods like groceries, clothing, and appliances; for services such as club memberships, hotel reservations, and event tickets; and for donations." }, { "type": "paragraph", "text": "Using in-app purchase, there are four types of content you can offer:" }, { "type": "list", "items": [ "Consumable content like lives or gems in a game. After purchase, consumable content depletes as people use it, and people can purchase it again.", "Non-consumable content like premium features in an app. Purchased non-consumable content doesn’t expire.", "Auto-renewable subscriptions to virtual content, services, and premium features in your app on an ongoing basis. An auto-renewable subscription continues to automatically renew at the end of each subscription period until people choose to cancel it.", "Non-renewing subscriptions to a service or content that lasts for a limited time, like access to an in-game battle pass. People purchase a non-renewing subscription each time they want to extend their access to the service or content." ] }, { "type": "paragraph", "text": "For marketing and business guidance, see In-app purchase and Auto-renewable subscriptions. For information about what you can and can’t sell in your app, including in-app purchase usage requirements and restrictions, see App Review Guidelines." }, { "type": "note", "text": "NoteFor apps with exceptionally large, frequently updated catalogs of one-time purchases or subscription content from multiple creators, or apps that provide subscriptions with optional add-on content as a single purchase within the app, the Advanced Commerce API allows you to manage your In-App Purchase catalog directly. See the Advanced Commerce API App Store support page for an overview, and see Advanced Commerce API for developer guidance." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Let people experience your app before making a purchase. People may be more inclined to invest in paid items or features after they’ve enjoyed your app and discovered its value. If you offer auto-renewable subscriptions, consider supporting limited free access to your content; for guidance, see Auto-renewable subscriptions." }, { "type": "paragraph", "text": "Design an integrated shopping experience. You don’t want people to think they’ve entered a different app when they browse and purchase your digital products. Present products and handle transactions in ways that mirror the style of your app." }, { "type": "paragraph", "text": "Use simple, succinct product names and descriptions. Titles that don’t truncate or wrap and plain, direct language can help people find products quickly." }, { "type": "paragraph", "text": "Display the total billing price for each in-app purchase you offer, regardless of type. People need to know the total billing amount for every purchase they consider." }, { "type": "paragraph", "text": "Display your store only when people can make payments. If someone canʼt make payments — for example, because of parental restrictions — consider hiding your store or displaying UI that explains why the store isnʼt available. For developer guidance, see canMakePayments." }, { "type": "paragraph", "text": "Use the default confirmation sheet. When someone initiates an in-app purchase, the system displays a confirmation sheet to help prevent accidental purchases. Don’t modify or replicate this sheet." } ] }, { "heading": "Supporting Family Sharing", "level": 3, "content": [ { "type": "paragraph", "text": "People can use Family Sharing to share access to their purchased content — such as auto-renewable subscriptions and non-consumable in-app purchases — with up to five additional family members, across all their Apple devices. To encourage people to take advantage of the Family Sharing support you offer, consider the following guidelines." }, { "type": "paragraph", "text": "Prominently mention Family Sharing in places where people learn about the content you offer. For example, including “Family” or “Shareable” in a subscription or item name and referring to Family Sharing in your sign-up screen can highlight the feature and help people make an informed choice." }, { "type": "paragraph", "text": "Help people understand the benefits of Family Sharing and how to participate. When you turn on Family Sharing, people can receive notifications about the change, depending on their current settings. For example, an existing subscriber whose sharing setting is turned off (the default) receives a notice from Apple that invites them to share their subscription with family members. Similarly, a family member can get a notification about content that’s being shared with them. (To learn more about the types of notifications people can receive, see Auto-renewable subscriptions.)" }, { "type": "paragraph", "text": "Aim to customize your in-app messaging so that it makes sense to both purchasers and family members. For example, when a family member views shared content for the first time, you might welcome them with wording like “Your family subscription includes…”." } ] }, { "heading": "Providing help with in-app purchases", "level": 3, "content": [ { "type": "paragraph", "text": "Sometimes, people need help with a purchase or want to request a refund. To help make this experience convenient, you can present custom UI within your app that provides assistance, offers alternative solutions, and helps people initiate the system-provided refund flow. For developer guidance, see beginRefundRequest(for:in:); for related guidance specific to auto-renewable subscriptions, see Helping people manage their subscriptions." }, { "type": "paragraph", "text": "Provide help that customers can view before they request a refund. In addition to including a link to the system-provided refund flow, your custom purchase-help screen can provide assistance you tailor to your app. For example, your custom screen might help people resolve problems with missing purchases, answer frequently asked questions about the in-app purchases you offer, and give people ways to submit feedback or contact you directly for support." }, { "type": "paragraph", "text": "Use a simple title for the refund action, like “Refund” or “Request a Refund”. The system-provided refund flow makes it clear that people request a refund from Apple, so there’s no need to reiterate this information." }, { "type": "paragraph", "text": "Help people find the problematic purchase. For each recent purchase you display, include contextual information that helps people identify the one they want. For example, you might display an image of the product — along with its name and description — and list the original purchase date." }, { "type": "paragraph", "text": "Consider offering alternative solutions. For example, if the customer didn’t receive the item they purchased, you might offer immediate fulfillment or a conciliatory item. Regardless of the alternatives you offer, make it clear that people can still request a refund." }, { "type": "paragraph", "text": "Make it easy for people to request a refund. Although your purchase-help screen can offer useful information and alternative solutions, make sure this content doesn’t create a barrier to requesting a refund. For example, avoid making people scroll or open another screen to reveal your refund-request button. When people choose your refund-request item, they automatically enter the system-provided refund flow shown below." }, { "type": "paragraph", "text": "Avoid characterizing or providing guidance on Apple’s refund policies. For example, don’t speculate about whether customers will receive the refund they request. To help people understand the refund-request process, you can provide a link to Request a refund for apps or content that you bought from Apple." } ] }, { "heading": "Auto-renewable subscriptions", "level": 2, "content": [ { "type": "paragraph", "text": "Call attention to subscription benefits during onboarding. By showing the value of your subscription when people first launch your app, you can educate them on how the app works and help them understand what they’ll gain by subscribing. Include a strong call to action and a clear summary of subscription terms (see Making signup effortless). For related guidance, see Onboarding." }, { "type": "paragraph", "text": "Offer a range of content choices, service levels, and durations. People appreciate the flexibility to choose the subscription that best meets their needs." }, { "type": "paragraph", "text": "Consider letting people try your content for free before signing up. Limited free access gives people the opportunity to sample your content and encourages people who already engaged with your content to sign up. For example, you might offer a freemium app, a metered paywall, or a free trial." }, { "type": "paragraph", "text": "Prompt people to subscribe at relevant times, like when they near their monthly limit of free content. Additionally, consider making it easy for people to subscribe at any time by including prompts at relevant points throughout your app." }, { "type": "paragraph", "text": "Encourage a new subscription only when someone isn’t already a subscriber. Otherwise, people may believe their existing subscription has lapsed when that’s not actually the case. If you offer the same subscription options in multiple apps or through your website, provide a sign-in option so people don’t think they have to pay multiple times for the same service." } ] }, { "heading": "Making signup effortless", "level": 3, "content": [ { "type": "paragraph", "text": "A simple and informative sign-up experience makes it easy for people to act on their interest in your content, whether they’re in your app or viewing your App Store product page." }, { "type": "paragraph", "text": "Provide clear, distinguishable subscription options. Use short, self-explanatory names that differentiate subscription options from one another, and specify the price and duration for each option. If you offer an introductory price, be sure to list the introductory price, the duration of the offer, and the standard price the customer pays after the offer ends." }, { "type": "paragraph", "text": "Simplify initial signup by asking only for necessary information. A lengthy sign-up process may lower your subscription conversion rate. Defer asking for additional information until after people have signed up." }, { "type": "paragraph", "text": "In your tvOS app, help people sign up or authenticate using another device. Instead of asking people to input information in your tvOS app, send a code to another device where they can enter the information you need." }, { "type": "paragraph", "text": "Give people more information in your app’s sign-up screen. In addition to including links to your Terms of Service and Privacy Policy in your app and App Store metadata, the in-app sign-up screen needs to include:" }, { "type": "list", "items": [ "The subscription name, duration, and the content or services provided during each subscription period", "The billing amount, correctly localized for the territories and currencies where the subscription is available for purchase", "A way for existing subscribers to sign in or restore purchases" ] }, { "type": "paragraph", "text": "For example, the Forest Explorer sign-up screen displays billing totals for monthly, biannual, and annual subscriptions in the most prominent positions. In subordinate positions, it shows breakdowns of the biannual and annual prices, so that people can compare the values and make an informed choice. The sign-up screen also contains a button that existing subscribers can use to restore their purchases." }, { "type": "paragraph", "text": "Clearly describe how a free trial works. It’s particularly important to make sure people know that when the free trial is over, a payment will be automatically initiated for the next subscription period. For example, the Ocean Journal sign-up screen explicitly states both the duration of the free trial and the amount that’s billed when it ends." }, { "type": "paragraph", "text": "Include a sign-up opportunity in your app’s settings. App and account settings are common places for people to look for a way to subscribe." } ] }, { "heading": "Supporting offer codes", "level": 3, "content": [ { "type": "paragraph", "text": "In iOS and iPadOS, subscription offer codes let you use both online and offline channels to give new, existing, and lapsed subscribers free or discounted access to your subscription content. For example, you might provide offer codes through email, give them out at a store or event, or print one on a physical product." }, { "type": "paragraph", "text": "There are two types of offer codes you can support:" }, { "type": "list", "items": [ "A one-time use code is a unique code you generate in App Store Connect. People can redeem a one-time use code through a redemption URL (a shareable link), within your app (when you support redemption), or by entering it in the App Store, where they’re prompted to install your app if they haven’t already. Consider using one-time use codes when your distribution is small or when you need to restrict access to a code.", "A custom code is a code you create, such as NEWYEAR or SPRINGSALE. People can redeem a custom code through a redemption URL or within your app (when you support redemption). Consider using a custom code when you want to support a large campaign that requires a mass distribution of codes." ] }, { "type": "paragraph", "text": "For developer guidance on implementing offer codes, see Offer codes and Set up offer codes. For guidance on other types of offers, see Providing subscription offers." }, { "type": "paragraph", "text": "Clearly explain offer details. To help people make an informed decision, provide a straightforward and succinct description of your offer in your marketing materials." }, { "type": "paragraph", "text": "Follow guidelines for creating a custom code. A custom code can contain only alphanumeric ASCII characters. Don’t use special characters, including Chinese and Arabic characters." }, { "type": "paragraph", "text": "Tell people how to redeem a custom code. Because people can’t redeem a custom code by entering it in their App Store account settings, it’s important to let them know that they can redeem it through a redemption URL or within your app." }, { "type": "paragraph", "text": "Consider supporting offer redemption within your app. The system automatically provides screens that present the offer-redemption flow, whether people redeem the offer in your app or in the App Store. When you use StoreKit API to let people redeem offer codes within your app, the only custom UI you need to create is one that initiates the system-provided flow. For developer guidance, see presentOfferCodeRedeemSheet(in:) and offerCodeRedemption(isPresented:onCompletion:). There are several natural places to provide this custom UI. For example, you could add a “Redeem Code” button to your paywall, onboarding screens, or your app’s settings screen." }, { "type": "paragraph", "text": "After people tap your custom redeem button, the system automatically provides a series of code-redemption screens like the ones shown below." }, { "type": "paragraph", "text": "Supply an engaging and informative promotional image. Creating this optional image can help people understand the value of your content. If you don’t supply a promotional image, the code redemption screens use your app icon by default. To learn more, see Promoting your in-app purchases." }, { "type": "paragraph", "text": "Help people benefit from unlocked content as soon as they complete the redemption flow. Think about ways to align the post-redemption experience in your app with the subscriber’s new status. For example, you might provide a welcome experience for new subscribers or a brief tour of new features for an existing subscriber who’s unlocked additional functionality. In particular, be prepared to welcome people who subscribe before they open your app for the first time. For example, if you require people to create an account or sign in before they can use your app, make this process as smooth as possible for new subscribers who haven’t experienced it before." } ] }, { "heading": "Helping people manage their subscriptions", "level": 3, "content": [ { "type": "paragraph", "text": "Supporting subscription management means people can upgrade, downgrade, or cancel a subscription without leaving your app. Offering subscription management within your app also gives you a natural place to provide help for common subscriber issues and present alternative offers for people to consider." }, { "type": "paragraph", "text": "Provide summaries of the customer’s subscriptions. In particular, people appreciate viewing the upcoming renewal date without having to search for it. Consider displaying this information in a settings or account screen, near the subscription-management option. For developer guidance, see Product.SubscriptionInfo." }, { "type": "paragraph", "text": "Consider using the system-provided subscription-management UI. Using StoreKit APIs lets you present a consistent experience that helps people manage or cancel their subscriptions without leaving your app. For developer guidance, see showManageSubscriptions(in:)." }, { "type": "paragraph", "text": "Consider ways to encourage a subscriber to keep their subscription or resubscribe later. When you use StoreKit APIs, your app is notified when someone chooses to cancel their subscription. In this scenario, you might want to extend a personalized offer as an alternative to cancellation or invite people to describe their reasons for canceling in an exit survey. In addition to giving you insights into various customer problems, survey feedback can also help inform messaging for retention and win-back strategies." }, { "type": "paragraph", "text": "Always make it easy for customers to cancel an auto-renewable subscription. If the manage subscription action is deep within an app — or hard to recognize — subscribers can feel they’re being discouraged or prevented from canceling." }, { "type": "paragraph", "text": "Consider creating a branded, contextual experience to complement the system-provided management UI. Within your custom UI, you might offer a popular premium tier or provide personalized suggestions for alternative plans based on what you know about the customer’s preferences or how they use your app. For example, you can create a promotional offer that provides a discounted price for a specific period of time. You might also consider subscription offer codes to help you win back lapsed subscribers and encourage existing subscribers to upgrade." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "The sign-up screen in your watchOS app needs to display the same set of information about your subscription options that you display in other versions of your app. For the complete list of required items, see Making signup effortless. The following guidelines can help you design a sign-up screen that feels at home on Apple Watch." }, { "type": "paragraph", "text": "Clearly describe the differences between versions of your app that run on different devices. If your watchOS app supports different functionality or provides a subset of the content that’s available on other devices, be sure to clarify these differences in your description. Be straightforward about the advantages of accessing subscription content through your watchOS app without implying that the experience is identical to the ones in other versions of your app." }, { "type": "paragraph", "text": "A description that might lead people to expect access to 90,000 maps on their Apple Watch" }, { "type": "paragraph", "text": "A description that clarifies how the subscription works on Apple Watch in contrast with other devices" }, { "type": "paragraph", "text": "Consider using a modal sheet to display the required information. After people respond to your call to action to learn more about your subscription offers, you can use a modal sheet to present all required items in a single view. Even though people must scroll the view to access all the information, displaying it in a modal sheet helps your app UI remain streamlined and concise. Also, a modal sheet’s default Close button makes it easy for people to return to your free content with one tap. If you create a custom sign-up view instead of using a modal sheet, design a complete, efficient flow and include a Close or Cancel button that lets people return to your free content." }, { "type": "paragraph", "text": "Make subscription options easy to compare on a small screen. People need to understand the terms of each subscription option before they can choose one. Aim to display the duration and discount information for each option in a compact way that’s easy to scan and compare. Here are two ways you might present subscription options in your watchOS app:" }, { "type": "list", "items": [ "Display each option in a separate button. Using one button per payment option lets people start the signup process with one tap. In this design, it’s important to lock up each button with its description so that people can see how these elements are related, especially while scrolling.", "Display a list of options, followed by a button people tap to start the signup process. Using a list to display one option per row gives you a compact design that minimizes scrolling while making subscription choices easy to scan and understand. In this design, the button’s title can update to reflect the chosen option." ] }, { "type": "paragraph", "text": "One payment option per button" }, { "type": "paragraph", "text": "One payment option per list row, followed by a button that updates to display the chosen option" } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "In-App Purchase" }, { "type": "paragraph", "text": "Offering Subscriptions" }, { "type": "paragraph", "text": "App Review Guidelines" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "In-App Purchase — StoreKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 12, 2023", "Updated artwork and guidance for redeeming offer codes." ], [ "November 3, 2022", "Added a guideline for displaying the total billing price for every in-app purchase item and consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Apple Pay", "url": "/design/human-interface-guidelines/apple-pay" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/in-app-purchase#Best-practices" }, { "title": "Auto-renewable subscriptions", "url": "/design/human-interface-guidelines/in-app-purchase#Auto-renewable-subscriptions" }, { "title": "Supporting Family Sharing", "url": "/design/human-interface-guidelines/in-app-purchase#Supporting-Family-Sharing" }, { "title": "Providing help with in-app purchases", "url": "/design/human-interface-guidelines/in-app-purchase#Providing-help-with-in-app-purchases" }, { "title": "Helping people manage their subscriptions", "url": "/design/human-interface-guidelines/in-app-purchase#Helping-people-manage-their-subscriptions" }, { "title": "Making signup effortless", "url": "/design/human-interface-guidelines/in-app-purchase#Making-signup-effortless" }, { "title": "Onboarding", "url": "/design/human-interface-guidelines/onboarding" }, { "title": "Supporting offer codes", "url": "/design/human-interface-guidelines/in-app-purchase#Supporting-offer-codes" }, { "title": "offer codes", "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase#Supporting-offer-codes" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/in-app-purchase#Platform-considerations" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/in-app-purchase#watchOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/in-app-purchase#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/in-app-purchase#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/in-app-purchase#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/in-app-purchase#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/in-app-purchase#Change-log" } ], "image_count": 0 }, { "title": "Live Photos", "url": "https://developer.apple.com/design/human-interface-guidelines/live-photos", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "When Live Photos is available, the Camera app captures additional content — including audio and extra frames — before and after people take a photo. People press a Live Photo to see it spring to life." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Apply adjustments to all frames. If your app lets people apply effects or adjustments to a Live Photo, make sure those changes are applied to the entire photo. If you don’t support this, give people the option of converting it to a still photo." }, { "type": "paragraph", "text": "Keep Live Photo content intact. It’s important for people to experience Live Photos in a consistent way that uses the same visual treatment and interaction model across all apps. Don’t disassemble a Live Photo and present its frames or audio separately." }, { "type": "paragraph", "text": "Implement a great photo sharing experience. If your app supports photo sharing, let people preview the entire contents of Live Photos before deciding to share. Always offer the option to share Live Photos as traditional photos." }, { "type": "paragraph", "text": "Clearly indicate when a Live Photo is downloading and when the photo is playable. Show a progress indicator during the download process and provide some indication when the download is complete." }, { "type": "paragraph", "text": "Display Live Photos as traditional photos in environments that don’t support Live Photos. Don’t attempt to replicate the Live Photos experience provided in a supported environment. Instead, show a traditional, still representation of the photo." }, { "type": "paragraph", "text": "Make Live Photos easily distinguishable from still photos. The best way to identify a Live Photo is through a hint of movement. Because there are no built-in Live Photo motion effects, like the one that appears as you swipe through photos in the full-screen browser of Photos app, you need to design and implement custom motion effects." }, { "type": "paragraph", "text": "In cases where movement isn’t possible, show a system-provided badge above the photo, either with or without text. Never include a playback button that a viewer can interpret as a video playback button." }, { "type": "paragraph", "text": "Keep badge placement consistent. If you show a badge, put it in the same location on every photo. Typically, a badge looks best in a corner of a photo." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "In visionOS, people can view a Live Photo, but they can’t capture one." } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "PHLivePhoto — PhotoKit" }, { "type": "paragraph", "text": "LivePhotosKit JS — LivePhotosKit JS" } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/live-photos#Best-practices" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/live-photos#Platform-considerations" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/live-photos#visionOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/live-photos#Resources" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/live-photos#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/live-photos#Videos" } ], "image_count": 0 }, { "title": "Mac Catalyst", "url": "https://developer.apple.com/design/human-interface-guidelines/mac-catalyst", "category": "technologies", "summary": "", "sections": [ { "heading": "Before you start", "level": 2, "content": [ { "type": "paragraph", "text": "Many iPad apps are great candidates for creating a Mac app built with Mac Catalyst. This is especially true for apps that already work well on iPad and support key iPad features, such as:" }, { "type": "paragraph", "text": "Drag and drop. When you support drag and drop in your iPad app, you also get support for drag and drop in the Mac version." }, { "type": "paragraph", "text": "Keyboard navigation and shortcuts. Even though a physical keyboard may not always be available on iPad, iPad users appreciate using the keyboard to navigate and keyboard shortcuts to streamline their interactions. On the Mac, people expect apps to offer both keyboard navigation and shortcuts." }, { "type": "paragraph", "text": "Multitasking. Apps that do a good job scaling the interface to support Split View, Slide Over, and Picture in Picture lay the necessary groundwork to support the extensive window resizability that Mac users expect." }, { "type": "paragraph", "text": "Multiple windows. By supporting multiple scenes on iPad, you also get support for multiple windows in the macOS version of your app." }, { "type": "paragraph", "text": "Although great iPad apps can provide a solid foundation for creating a Mac app built with Mac Catalyst, some apps rely on frameworks or features that don’t exist on a Mac. For example, if the essential features of your experience require capabilities like gyroscope, accelerometer, or rear camera, frameworks like HealthKit or ARKit, or if the primary function you offer is something like marking, handwriting, or navigation, your app might not be suitable for the Mac." }, { "type": "paragraph", "text": "Creating a Mac version of your iPad app with Mac Catalyst gives the app automatic support for fundamental macOS features such as:" }, { "type": "list", "items": [ "Pointer interactions and keyboard-based focus and navigation", "Window management", "Toolbars", "Rich text interaction, including copy and paste as well as contextual menus for editing", "File management", "Menu bar menus", "App-specific settings in the system-provided Settings app" ] }, { "type": "paragraph", "text": "System-provided UI elements take on a more Mac-like appearance, too; for example:" }, { "type": "list", "items": [ "Split view", "File browser", "Activity view", "Form sheet", "Contextual actions", "Color picker" ] }, { "type": "paragraph", "text": "To learn more about the characteristics that distinguish the Mac experience, see Designing for macOS. For developer guidance, see Mac Catalyst." }, { "type": "note", "text": "Developer noteTo discover how views and controls can change when you create a Mac app using Mac Catalyst, download UIKit Catalog: Creating and customizing views and controls and build the macOS target." } ] }, { "heading": "Choose an idiom", "level": 2, "content": [ { "type": "paragraph", "text": "When you first create your Mac app using Mac Catalyst, Xcode defaults to the “Scale Interface to Match iPad” setting, or iPad idiom. With this setting, the system ensures that your Mac app appears consistent with the macOS display environment without requiring significant changes to the app’s layout. However, text and graphics may appear slightly less detailed because iPadOS views and text scale down to 77% in macOS when you use the iPad idiom. For example, the system scales text that uses the iPadOS baseline font size of 17pt down to 13pt in macOS." }, { "type": "paragraph", "text": "When your app feels at home on the Mac using the iPad idiom, consider switching to the Mac idiom. With this setting, text and artwork render in more detail, some interface elements and views take on an even more Mac-like appearance, and graphics-intensive apps may see improved performance and lower power consumption." }, { "type": "paragraph", "text": "You’re most likely to benefit from the Mac idiom if your app displays a lot of text, detailed artwork, or animations, but choosing this idiom can also mean that you need to spend additional time updating your Mac app’s layout, text, and images." }, { "type": "paragraph", "text": "When you adopt the Mac idiom, thoroughly audit your app’s layout, and plan to make changes to it. To help with this effort, consider using a separate asset catalog to contain your Mac app’s assets instead of reusing the asset catalog that contains your iPad app’s assets." }, { "type": "paragraph", "text": "Adjust font sizes as needed. With the Mac idiom, text renders at 100% of its configured size, which can appear too large without adjustment. When possible, use text styles and avoid fixed font sizes." }, { "type": "paragraph", "text": "Make sure views and images look good in the Mac version of your app. With the Mac idiom, iPadOS views render at 100% of their size, making them appear more detailed. To help you visualize the difference, consider the two depictions of an image asset shown below. One version illustrates how the asset appears when you use the iPad idiom, and the other version shows how the asset appears when you adopt the Mac idiom. Both depictions are zoomed in to show how the image renders with more details when you use the Mac idiom." }, { "type": "note", "text": "Developer noteWhen you adopt the Mac idiom, the unscaled views and interface elements report different metrics, often resulting in a significant amount of additional work. To reduce the amount of work, avoid using fixed font, view, or layout sizes. For developer guidance, see Choosing a user interface idiom for your Mac app." }, { "type": "paragraph", "text": "Limit your appearance customizations to standard macOS appearance customizations that are the same or similar to those available in iPadOS. Not all appearance customizations available to iPadOS controls are available to macOS controls." } ] }, { "heading": "Integrate the Mac experience", "level": 2, "content": [ { "type": "paragraph", "text": "When you use Mac Catalyst to create a Mac version of your iPad app, you need to ensure that your Mac app gives people a rich Mac experience. Regardless of the idiom you choose, it’s essential to go beyond simply displaying your iPadOS layout in a macOS window." }, { "type": "paragraph", "text": "iPadOS and macOS each define patterns and conventions that are rooted in the different ways people use their devices. Before you dive in and update specific views and controls, become familiar with the main differences between the platforms so you can create a great Mac app." } ] }, { "heading": "Navigation", "level": 3, "content": [ { "type": "paragraph", "text": "Many iPad and Mac apps organize data in similar ways, but they use different controls and visual indicators to help people understand and navigate through the data." }, { "type": "paragraph", "text": "Typically, iPad apps use the following components to organize their content and features:" }, { "type": "list", "items": [ "Split views. A split view supports hierarchical navigation, which consists of a two- or three-column interface that shows a primary column, an optional supplementary column, and a secondary pane of content. Frequently, apps use the primary column to create a sidebar-based interface where changes in the sidebar drive changes in the optional supplementary column, which then affect the content in the content pane.", "Tab bars. A tab bar supports flat navigation by displaying top-level categories in a persistent bar at the bottom of the screen.", "Page controls. A page control displays dots at the bottom of the screen that indicate the position of the current page in a flat list of pages." ] }, { "type": "paragraph", "text": "If you use a tab bar in your iPad app, consider using a split view with a sidebar or a segmented control. Both items are similar to macOS navigation conventions. To choose between a split view or a segmented control, consider the following:" }, { "type": "list", "items": [ "A split view with a sidebar displays a list of top-level items, each of which can disclose a list of child items. Using a sidebar streamlines navigation, because each tab’s contents are available within the sidebar. By using a sidebar on both iPad and Mac, you create a consistent layout that makes it easy for iPad users to start using the Mac version of your app.", "A segmented control and a tab bar both accommodate similar interactions, such as mutually exclusive selection. In general, using a split view instead of a tab bar works better than using a segmented control. However, a segmented control can work well on the Mac if your app uses a flat navigation hierarchy." ] }, { "type": "paragraph", "text": "Make sure people retain access to important tab-bar items in the Mac version of your app. Regardless of whether you use a split view or a segmented control instead of a tab bar in your iPad app, be sure to give people quick access to top-level items by listing them in the macOS View menu." }, { "type": "paragraph", "text": "Offer multiple ways to move between pages. Mac users — especially those who interact using a pointing device or only the keyboard — appreciate Next and Previous buttons in addition to iPad or trackpad gestures that let them swipe between pages." } ] }, { "heading": "Inputs", "level": 3, "content": [ { "type": "paragraph", "text": "Although both iPad and Mac accept user input from a range of devices — such as keyboard, mouse, and trackpad — touch interactions are the basis for iPadOS conventions. In contrast, keyboard and mouse interactions inform most macOS conventions." }, { "type": "paragraph", "text": "Most iPadOS gestures convert automatically when you create your Mac app using Mac Catalyst; for example:" }, { "type": "table", "rows": [ [ "iPadOS gesture…", "Translates to mouse interaction" ], [ "Tap", "Left or right click" ], [ "Touch and hold", "Click and hold" ], [ "Pan", "Left click and drag" ] ] }, { "type": "table", "rows": [ [ "iPadOS gesture…", "Translates to trackpad gesture" ], [ "Tap", "Click" ], [ "Touch and hold", "Click and hold" ], [ "Pan", "Click and drag" ], [ "Pinch", "Pinch" ], [ "Rotate", "Rotate" ] ] }, { "type": "note", "text": "Developer noteThe system sends the two touches in the pinch and rotate gestures to the view under the pointer, not the view under each touch." } ] }, { "heading": "App icons", "level": 3, "content": [ { "type": "paragraph", "text": "Create a macOS version of your app icon. Great macOS app icons showcase the lifelike rendering style that people expect in macOS while maintaining a harmonious experience across all platforms." } ] }, { "heading": "Layout", "level": 3, "content": [ { "type": "paragraph", "text": "To take advantage of the wider Mac screen in ways that give Mac users a great experience, consider updating your layout in the following ways:" }, { "type": "list", "items": [ "Divide a single column of content and actions into multiple columns.", "Use the regular-width and regular-height size classes, and consider reflowing elements in the content area to a side-by-side arrangement as people resize the window.", "Present an inspector UI next to the main content instead of using a popover." ] }, { "type": "paragraph", "text": "Consider moving controls from the main UI of your iPad app to your Mac app’s toolbar. Be sure to list the commands associated with these controls in the menus of your Mac app’s menu bar." }, { "type": "paragraph", "text": "As much as possible, adopt a top-down flow. Mac apps place the most important actions and content near the top of the window. If your iPad app provides controls in a toolbar, put these controls in the window toolbar of the macOS version of your app." }, { "type": "paragraph", "text": "Relocate buttons from the side and bottom edges of the screen. On iPad, placing buttons on these screen edges can help people reach them, but on a Mac, this ergonomic consideration doesn’t apply. You may want to relocate these controls to other areas or put them in the toolbar of your macOS window." } ] }, { "heading": "Menus", "level": 3, "content": [ { "type": "paragraph", "text": "Mac users are familiar with the persistent menu bar and expect to find all of an app’s commands in it. In contrast, iPadOS doesn’t have a persistent menu bar, and iPad users expect to find app commands within the app’s UI or in the shortcut interface that displays when they hold the Command key on a connected keyboard." }, { "type": "note", "text": "Developer noteTo support keyboard shortcuts for menu commands, use UIKeyCommand. For developer guidance, see Adding menus and shortcuts to the menu bar and user interface." }, { "type": "paragraph", "text": "If you provide pop-up buttons or pull-down buttons that reveal a menu in your iPad app, the menu automatically takes on a macOS appearance in the Mac app you create with Mac Catalyst." }, { "type": "note", "text": "Developer noteTo add and remove custom app menus, use UIMenuBuilder and add menu items that represent your iPad app’s commands as menu items with UICommand." }, { "type": "paragraph", "text": "The system automatically converts the context menus in your iPad app to context menus in the macOS version of your app. As you create the Mac version of your app, consider looking for additional places to support context menus. Mac users tend to expect every object in your app to offer a context menu of relevant actions. Note that on a Mac, a context menu is sometimes called a contextual menu." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iPadOS or macOS. Not supported in iOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Designing for macOS" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Mac Catalyst — UIKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Before you start", "url": "/design/human-interface-guidelines/mac-catalyst#Before-you-start" }, { "title": "Designing for macOS", "url": "/design/human-interface-guidelines/designing-for-macos" }, { "title": "Choose an idiom", "url": "/design/human-interface-guidelines/mac-catalyst#Choose-an-idiom" }, { "title": "Integrate the Mac experience", "url": "/design/human-interface-guidelines/mac-catalyst#Integrate-the-Mac-experience" }, { "title": "Navigation", "url": "/design/human-interface-guidelines/mac-catalyst#Navigation" }, { "title": "Split views", "url": "/design/human-interface-guidelines/split-views" }, { "title": "Tab bars", "url": "/design/human-interface-guidelines/tab-bars" }, { "title": "Page controls", "url": "/design/human-interface-guidelines/page-controls" }, { "title": "Inputs", "url": "/design/human-interface-guidelines/mac-catalyst#Inputs" }, { "title": "App icons", "url": "/design/human-interface-guidelines/mac-catalyst#App-icons" }, { "title": "Layout", "url": "/design/human-interface-guidelines/mac-catalyst#Layout" }, { "title": "Menus", "url": "/design/human-interface-guidelines/mac-catalyst#Menus" }, { "title": "pop-up buttons", "url": "https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons" }, { "title": "pull-down buttons", "url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/mac-catalyst#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/mac-catalyst#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/mac-catalyst#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/mac-catalyst#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/mac-catalyst#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/mac-catalyst#Change-log" } ], "image_count": 0 }, { "title": "Machine learning", "url": "https://developer.apple.com/design/human-interface-guidelines/machine-learning", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "In addition to providing familiar features like image recognition and content recommendations, your app can use machine learning to forge deep connections with people and help them accomplish more with less effort." }, { "type": "paragraph", "text": "For related guidance on how to use machine learning models to enable intelligent content creation experiences, see Generative AI." } ] }, { "heading": "Planning your design", "level": 2, "content": [ { "type": "paragraph", "text": "Machine learning apps use models to perform tasks like recognizing images or finding relationships among numerical data. A great machine learning app depends on well-designed models as much as it depends on a well-designed UI and user experience. For insight into the process of designing models, see Create ML." }, { "type": "paragraph", "text": "As you design your models, keep the intended experience of your app in mind. It can take a long time to adjust the behavior of models, so be prepared to change the way you use data and metrics if the app experience needs to change." }, { "type": "paragraph", "text": "Designing the UI and user experience of a machine learning app can be uniquely challenging. Because a machine learning app bases its behavior on the data it receives — reacting to changing information and conditions — you can’t design specific reactions to a static set of scenarios. Instead, you design the experience by teaching the app how to interpret data and react accordingly." }, { "type": "paragraph", "text": "To help you meet this challenge, first consider the role that machine learning plays in your app. Defining the role of machine learning in your app can help you discover areas in which you can explore the ways machine learning can affect the experience your app provides." }, { "type": "paragraph", "text": "Use the machine learning role you identify to help you define ways your app can receive and display data. There are several patterns — grouped into inputs and outputs — that provide guidance in areas such as getting feedback, displaying data, handling mistakes, and supporting corrections. Use the guidance in these patterns to help you integrate machine learning into your app in ways that people appreciate." } ] }, { "heading": "The role of machine learning in your app", "level": 2, "content": [ { "type": "paragraph", "text": "Machine learning systems vary widely, and the ways an app can use machine learning vary widely, too. As you approach the design of your app, think about how its features use machine learning in each of the following areas." } ] }, { "heading": "Critical or complementary", "level": 3, "content": [ { "type": "paragraph", "text": "If an app can still work without the feature that machine learning supports, machine learning is complementary to the app; otherwise, it’s a critical dependency. For example:" }, { "type": "list", "items": [ "The keyboard uses machine learning to provide QuickType suggestions. Because the keyboard still works without these suggestions, machine learning plays a complementary role in the app.", "Face ID relies on machine learning to perform accurate face recognition. Without machine learning, Face ID would not work." ] }, { "type": "paragraph", "text": "In general, the more critical an app feature is, the more people need accurate and reliable results. On the other hand, if a complementary feature delivers results that aren’t always of the highest quality, people might be more forgiving." } ] }, { "heading": "Private or public", "level": 3, "content": [ { "type": "paragraph", "text": "Machine learning results depend on data. To make good design decisions, you need to know as much as possible about the types of data your app feature needs. In general, the more sensitive the data, the more serious the consequences of inaccurate or unreliable results. For example:" }, { "type": "list", "items": [ "If a health app misinterprets data and incorrectly recommends a visit to the doctor, people are likely to experience anxiety and may lose trust in the app.", "If a music app misinterprets data and recommends an artist that people don’t like, they’re likely to view the result as an inconsequential mistake." ] }, { "type": "paragraph", "text": "As with critical app features, features that use sensitive data must prioritize accuracy and reliability. Regardless of the sensitivity of the data, all apps must protect user privacy at all times." } ] }, { "heading": "Proactive or reactive", "level": 3, "content": [ { "type": "paragraph", "text": "A proactive app feature provides results without people requesting it to do so. Proactive features can prompt new tasks and interactions by providing unexpected, sometimes serendipitous results. In contrast, a reactive app feature provides results when people ask for them or when they take certain actions. Reactive features typically help people as they perform their current task. For example:" }, { "type": "list", "items": [ "QuickType suggests words in reaction to what people type.", "Siri Suggestions can proactively suggest a shortcut based on people’s recent routines." ] }, { "type": "paragraph", "text": "Because people don’t ask for the results that a proactive feature provides, they may have less tolerance for low-quality information. To reduce the possibility that people will find proactive results intrusive or irrelevant, you may need to use additional data for the feature." } ] }, { "heading": "Visible or invisible", "level": 3, "content": [ { "type": "paragraph", "text": "Apps may use machine learning to support visible or invisible features. People are usually aware of visible app features because such features tend to offer suggestions or choices that people view and interact with. For example, a visible keyboard feature tries to guess the word that people are typing and presents the most likely words in a list from which people choose." }, { "type": "paragraph", "text": "As the name suggests, an invisible feature provides results that aren’t obvious to people. For example, the keyboard learns how people type over time so it can optimize the tap area for each key and help them make fewer typing mistakes. Because this app feature improves the typing experience without requiring people to make choices, many people aren’t aware that the feature exists." }, { "type": "paragraph", "text": "People’s impression of the reliability of results can differ depending on whether a feature is visible or invisible. With a visible feature, people form an opinion about the feature’s reliability as they choose from its results. It’s harder for an invisible feature to communicate its reliability — and potentially receive feedback — because people may not be aware of the feature at all." } ] }, { "heading": "Dynamic or static", "level": 3, "content": [ { "type": "paragraph", "text": "All machine learning models can improve, but some improve dynamically, as people interact with the app feature, and others improve offline and affect the feature only when the app updates. For example:" }, { "type": "list", "items": [ "Face ID improves dynamically as people’s faces gradually change over time.", "Photos improves its object recognition capabilities with every new iOS release." ] }, { "type": "paragraph", "text": "In addition to the frequency of app updates, static or dynamic improvements can affect other parts of the user experience, too. For example, dynamic features often incorporate forms of calibration and feedback (either implicit or explicit), whereas static features might not." } ] }, { "heading": "Explicit feedback", "level": 2, "content": [ { "type": "paragraph", "text": "Explicit feedback provides actionable information your app can use to improve the content and experience it presents to people. Unlike implicit feedback — which is information an app gleans from user actions — explicit feedback is information people provide in response to a specific request from the app." }, { "type": "paragraph", "text": "Favoriting — marking an item for quick access in the future — and social feedback — expressing emotions towards others — are common user interactions that seem like mechanisms that supply explicit feedback. However, these tools actually provide implicit feedback because they don’t support app-specific requests. People use favoriting and social feedback to accomplish their own goals and apps can gather implicit feedback from these interactions." }, { "type": "paragraph", "text": "Request explicit feedback only when necessary. People must take action to provide explicit feedback, so it’s best to avoid requesting it if possible. Instead, consider using implicit feedback to learn how people interact with your app without asking them to do extra work." }, { "type": "paragraph", "text": "Always make providing explicit feedback a voluntary task. You want to communicate that explicit feedback can help improve the experience without making people feel that providing it is mandatory." }, { "type": "paragraph", "text": "Use simple, direct language to describe each explicit feedback option and its consequences. Avoid using imprecise terms such as dislike because such terms don’t convey consequences and can be hard to translate. Instead, describe each option in a way that helps people understand what happens when they choose the option, such as:" }, { "type": "list", "items": [ "Suggest less pop music", "Suggest more thrillers", "Mute politics for a week" ] }, { "type": "paragraph", "text": "Add icons to an option description if it helps people understand it. Icons can help clarify or emphasize part of an option description. Avoid using an icon by itself, because it might not be clear enough to communicate granularity or consequences." }, { "type": "paragraph", "text": "Consider offering multiple options when requesting explicit feedback. Providing multiple options can give people a sense of control and help them identify unwanted suggestions and remove them from your app. To help people provide feedback, consider offering options that become progressively more specific so that it’s easy for people to clarify their response." }, { "type": "paragraph", "text": "Act immediately when you receive explicit feedback and persist the resulting changes. For example, if people identify content they don’t want to see, that the content instantly disappears from their view and doesn’t appear elsewhere in your app. When you react immediately to feedback and show that your app remembers it, you build people’s trust in the value of providing it." }, { "type": "paragraph", "text": "Consider using explicit feedback to help improve when and where you show results. For example, people might like a result, but they may not want to see it at certain times or in certain contexts. Explicit feedback on when and where to show results can help you fine-tune the experience people have in your app." } ] }, { "heading": "Implicit feedback", "level": 2, "content": [ { "type": "paragraph", "text": "Implicit feedback is information that arises as people interact with your app’s features. Unlike the specific responses you get from explicit feedback, implicit feedback gives you a wide range of information about user behavior and preferences. Although incorporating implicit feedback isn’t required for a great machine learning app, the feedback can help you improve your app’s user experience without asking people to do any extra work." }, { "type": "paragraph", "text": "Always secure people’s information. Implicit feedback can gather potentially sensitive user information, so you must be particularly careful to maintain strict controls on user privacy." }, { "type": "paragraph", "text": "Help people control their information. As an app developer, you know that the more you understand about the behavior of your users — both within your app and in other apps — the more you can improve the experience your app provides. Although most people understand the benefits of making their information available to multiple apps, they may still be surprised when things they do in one app affect experiences they have in a different app. Worse, people may assume that apps are sharing their private information, which can cause them to lose trust in the apps. It’s important to tell people how your app gets and shares their information and to give people ways to restrict the flow of their information." }, { "type": "paragraph", "text": "Don’t let implicit feedback decrease people’s opportunities to explore. Implicit feedback tends to reinforce people’s behavior, which can improve the user experience in the short term, but may worsen it in the long term. For example, it might seem like a good idea to give people a set of suggestions that matches all the things they’re interested in now, but doing so doesn’t encourage them to explore new things." }, { "type": "paragraph", "text": "When possible, use multiple feedback signals to improve suggestions and mitigate mistakes. Implicit feedback is indirect, so it can be difficult to discern a person’s actual intent in the information you gather. For example, if someone views a photo, shares it in a message, and adds it to a shared album, it doesn’t necessarily mean they have positive feelings about the photo. Incorporate implicit feedback from multiple sources and interactions to help you avoid misinterpreting people’s intentions." }, { "type": "paragraph", "text": "Consider withholding private or sensitive suggestions. People often share their accounts and devices with others, or switch from using a personal device to a communal one. If your app receives implicit feedback related to private or sensitive topics, avoid offering recommendations based on that feedback." }, { "type": "paragraph", "text": "Prioritize recent feedback. People’s tastes can change frequently, so base your recommendations on recent implicit feedback. For example, Face ID prioritizes recent facial input because it’s most likely to represent what the person looks like now. If recent feedback isn’t available, you can fall back to historical feedback." }, { "type": "paragraph", "text": "Use feedback to update predictions on a cadence that matches the person’s mental model of the feature. For example, people expect typing suggestions to update immediately as they’re typing. On the other hand, giving people continuously updated song recommendations makes it hard to consider individual songs and could make them feel rushed or overwhelmed." }, { "type": "paragraph", "text": "Be prepared for changes in implicit feedback when you make changes to your app’s UI. Even small UI changes can lead to noticeable changes in the amount and types of implicit feedback. For example, changing the location of a button can affect how people use it, even if there’s no change in the benefit they get from the button’s action. Take such changes into account when interpreting the implicit feedback you receive from interactions in your app." }, { "type": "paragraph", "text": "Beware of confirmation bias. Implicit feedback is constrained by what people can actually see and do in your app and other apps — it rarely gives you insight into new things they might like to do. Avoid relying solely on implicit feedback to inform your results." } ] }, { "heading": "Calibration", "level": 2, "content": [ { "type": "paragraph", "text": "Calibration is a process during which people provide information that an app feature needs before it can function. To use Face ID, for example, a person must first scan their face." }, { "type": "paragraph", "text": "In general, only use calibration when your feature can’t function without that initial information. If your feature can work without calibration, consider using other ways to gather the information you need, such as implicit feedback or possibly explicit feedback." }, { "type": "paragraph", "text": "Always secure people’s information. During calibration, people may provide sensitive information and you must make sure it remains secure." }, { "type": "paragraph", "text": "Be clear about why you need people’s information. Typically, calibration is required before people can use a feature, so it’s essential that they understand the value of providing their information. As you briefly describe how people can benefit from your feature, emphasize what it does rather than how it works." }, { "type": "paragraph", "text": "Collect only the most essential information. Designing a unique experience that requests a minimal amount of information can make people more comfortable participating in the process and increase their trust in your app." }, { "type": "paragraph", "text": "Avoid asking people to participate in calibration more than once. Also, it’s best when calibration occurs early in the user experience. As people continue using your app or feature, you can use implicit or explicit feedback to evolve your information about them without asking them to participate again. An exception is a feature that needs calibration with an object instead of a person. For example, an app that helps people improve their baseball swing might need to calibrate with each new baseball field." }, { "type": "paragraph", "text": "Make calibration quick and easy. Even a brief calibration experience takes time and requires effort from people. An ideal calibration experience makes it easy for people to respond, without compromising the quality of the information they provide. The following guidelines can help you create a streamlined calibration experience." }, { "type": "list", "items": [ "Prioritize getting a few pieces of important information and infer the rest from other sources or by getting people’s feedback.", "Avoid asking for information that most people would have to look up.", "Avoid asking people to perform actions that might be difficult." ] }, { "type": "paragraph", "text": "Make sure people know how to perform calibration successfully. After people decide to participate in calibration, give them an explicit goal and show their progress towards it. For example, Face ID calibration briefly describes what people need to do and changes the appearance of the tick marks encircling the face as people progress through scanning." }, { "type": "paragraph", "text": "Immediately provide assistance if progress stalls. When progress stalls, people can feel stuck or powerless, and they may lose trust in your app. In this situation, it’s crucial to give people actionable recommendations that quickly get them back on track. As you provide this guidance, never imply that something’s wrong or that people are at fault, and never leave people without a clear next step." }, { "type": "paragraph", "text": "Confirm success. The moment people successfully complete calibration, reward their time and effort by giving them a clear path towards using the feature. Providing an explicit completion to the calibration experience reinforces the unique nature of the experience and helps people switch their focus to your feature." }, { "type": "paragraph", "text": "Let people cancel calibration at any time. Make sure you give people an easy way to cancel the experience at any point and avoid implying any judgement about their choice. There’s no need to provide any messaging that mentions the canceled calibration, because the next time people attempt to use the feature, they’ll have another chance to participate." }, { "type": "paragraph", "text": "Give people a way to update or remove information they provided during calibration. Letting people edit their information gives them more control and can lead them to have greater trust in your app. Although the calibration experience can help people edit their responses, it’s a good idea to let people edit their information outside of the calibration experience so that they feel free to make changes at any time." } ] }, { "heading": "Corrections", "level": 2, "content": [ { "type": "paragraph", "text": "People use corrections to fix mistakes that apps make. For example, if a photo app automatically crops a photo in a way people don’t like, they can correct the mistake by cropping the photo in a different way." }, { "type": "paragraph", "text": "Give people familiar, easy ways to make corrections. When your app makes a mistake, you don’t want people to be confused about how to correct it. You can avoid causing confusion by showing the steps your app takes as it performs the automated task. For example, Photos highlights the controls it uses to auto-crop a photograph so that people can use the same controls to refine or undo the results." }, { "type": "paragraph", "text": "Provide immediate value when people make a correction. Reward people’s effort by instantly displaying corrected content, especially when the feature is critical or you’re responding to direct user input. Also, be sure to persist the updates so people don’t have to make the same corrections again." }, { "type": "paragraph", "text": "Let people correct their corrections. Sometimes, people make a correction without realizing that they’ve made a mistake. As you do with all corrections, respond immediately to an updated correction and persist the update." }, { "type": "paragraph", "text": "Always balance the benefits of a feature with the effort required to make a correction. People may not mind when a feature that automates a task makes a mistake, but they’re likely to stop using the feature if it seems easier to perform the task themselves." }, { "type": "paragraph", "text": "Never rely on corrections to make up for low-quality results. Although corrections can reduce the impact of a mistake, depending on them may erode people’s trust in your app and reduce the value of your feature." }, { "type": "paragraph", "text": "Learn from corrections when it makes sense. A correction is a type of implicit feedback that can give you valuable information about ways your app doesn’t meet people’s expectations. Before you use a correction to update your models, make sure that the correction will lead to higher quality results." }, { "type": "paragraph", "text": "When possible, use guided corrections instead of freeform corrections. Guided corrections suggest specific alternatives, so they require less user effort; freeform corrections don’t suggest specific alternatives, so they require more input from people. An example of guided correction is a speech-to-text feature that gives people a list of alternative text completions from which to choose. In contrast, Photos offers freeform correction so that people can adjust the auto-cropping of a photo as they see fit. If it makes sense in your app, you can support a combination of guided and freeform corrections." } ] }, { "heading": "Mistakes", "level": 2, "content": [ { "type": "paragraph", "text": "It’s inevitable that your app will make mistakes. Although people may not expect perfection, mistakes can damage their experience and decrease their trust in your app. To help you avoid negative consequences, it’s crucial to:" }, { "type": "list", "items": [ "Anticipate mistakes. As much as possible, design ways to avoid mistakes and mitigate them when they happen.", "Help people handle mistakes. Mistakes can have a wide range of consequences, so the tools you provide to handle a mistake must be able to address those consequences.", "Learn from mistakes when doing so improves your app. In some cases, learning from a mistake might have undesirable effects, such as causing unpredictability in the user experience. When it makes sense, use each mistake as a data point that can refine your machine learning models and improve your app." ] }, { "type": "paragraph", "text": "There are several machine learning patterns that can help you address mistakes:" }, { "type": "list", "items": [ "Limitations help you set people’s expectations about the accuracy of your suggestions.", "Corrections give people a way to be successful even when your results are wrong.", "Attribution gives people insight into where suggestions come from, which can help them understand mistakes.", "Confidence helps you gauge the quality of your results, which can impact how you present them.", "Feedback — both explicit and implicit — lets people tell you about mistakes that you might not be aware of." ] }, { "type": "paragraph", "text": "Understand the significance of a mistake’s consequences. For example, incorrect keyboard suggestions might annoy people, but suggesting a travel route that results in a missed flight is a serious inconvenience. Show empathy by providing corrective actions or tools that match the seriousness of the mistake." }, { "type": "paragraph", "text": "Make it easy for people to correct frequent or predictable mistakes. If you don’t give people an easy way to correct mistakes, they can lose trust in your app." }, { "type": "paragraph", "text": "Continuously update your feature to reflect people’s evolving interests and preferences and help avoid mistakes. For example, you can use implicit feedback to discover changes in people’s tastes and habits. It’s also a good idea to update your feature with domain-specific information, such as current trends in popular entertainment. Ideally, people don’t have to do any work to benefit from improvements in your app." }, { "type": "paragraph", "text": "When possible, address mistakes without complicating the UI. Some patterns, such as corrections and limitations, tend to integrate seamlessly with an app’s UI, whereas others, like attributions, can be harder to integrate. Balance a pattern’s effect on the UI with its potential for compounding the mistake. For example, if you update the UI with an attribution that turns out to be wrong, the effect of the original mistake is magnified." }, { "type": "paragraph", "text": "Be especially careful to avoid mistakes in proactive features. A proactive feature — like a suggestion based on people’s behaviors — promises valuable results without asking people to do anything to get them. However, because people don’t request a proactive feature, they often have less patience with its mistakes. Mistakes made by proactive features can also cause people to feel that they have less control." }, { "type": "paragraph", "text": "As you work on reducing mistakes in one area, always consider the effect your work has on other areas and overall accuracy. For example, optimizing an image-recognition app to improve how it recognizes dogs might result in a decreased ability to recognize cats. As your models evolve, be prepared for mistakes to evolve, too. Use what you know about people’s preferences to help you determine the areas to work on." } ] }, { "heading": "Multiple options", "level": 2, "content": [ { "type": "paragraph", "text": "Depending on the design of your feature, it might work best to present a single result or multiple results from which people can choose. Providing multiple options can give people a greater sense of control and can help bridge the gap between your model’s predictions and what people actually want. Multiple options can also encourage people to have realistic expectations about the types of results your app generates." }, { "type": "paragraph", "text": "You might present multiple options to people in the following contexts:" }, { "type": "list", "items": [ "Suggested options, a proactive feature that suggests content to people based on the their past interactions. For example, For You recommendations from Apple Music.", "Requested options, a reactive feature that suggests potential next steps to people based on their recent actions. For example, Quick Type suggestions.", "Corrections, which are actions people take to fix mistakes your app has made when it’s acting on their behalf. For example, the Photos Auto-Crop feature." ] }, { "type": "paragraph", "text": "Prefer diverse options. When possible, balance the accuracy of a response with the diversity of multiple options. For example, Apple Maps generally suggests more than one route to a destination, such as a route without tolls, a scenic route, or a route that uses highways. Providing different types of options helps people choose the one that they prefer and can also suggest new items that might interest them." }, { "type": "paragraph", "text": "In general, avoid providing too many options. People must evaluate each option before making a choice, so more options increases cognitive load. When possible, list options on one screen so people don’t have to scroll to find the right one." }, { "type": "paragraph", "text": "List the most likely option first. When you know how your confidence values correlate with the quality of your results, you might use them to rank the options. You might also consider using contextual information, such as the time of day or the current location, to help you determine the most likely option. If it makes sense in your app, select the first option by default so people can quickly achieve their goals without reading through every option." }, { "type": "paragraph", "text": "Make options easy to distinguish and choose. For example, in a routing app, people often need to make route choices quickly to avoid going the wrong way. When options look similar, help people distinguish between them by providing a brief description of each one and taking particular care to highlight the differences. In cases where there are too many options to display in a single view, such as with content recommendations, consider grouping options in categories that people can scan rapidly." }, { "type": "paragraph", "text": "Learn from selections when it makes sense. People give you implicit feedback every time they make a selection. When it doesn’t adversely affect the user experience, use this feedback to refine the options you provide and increase the chance that you’ll present the most likely option first. In general, continuing to offer incorrect results is likely to decrease people’s trust in the quality of your app’s predictions." } ] }, { "heading": "Confidence", "level": 2, "content": [ { "type": "paragraph", "text": "Confidence indicates the measure of certainty for a result. Not all models produce confidence values by default, so you might consider generating them if you can use them to improve the user experience of your app." }, { "type": "paragraph", "text": "Although it might seem like higher confidence produces a higher quality result — and therefore a better user experience — it doesn’t necessarily work that way. You need to verify that your confidence values correspond to the quality of your results. For example, you might review values for multiple confidence thresholds or compare values across multiple versions of your app. If you’re not sure how your confidence values correlate with the quality of your results, it’s not a good idea to convey confidence to people." }, { "type": "paragraph", "text": "Know what your confidence values mean before you decide how to present them. For example, people may forgive low-quality results from critical or complementary features — especially when results are accompanied by attribution or other contextual information — but presenting low-quality results in a prominent way is likely to erode trust in your app." }, { "type": "paragraph", "text": "In general, translate confidence values into concepts that people already understand. Simply displaying a confidence value doesn’t necessarily help people understand how it relates to a result. For example, a feature that suggests new music based on a person’s listening habits might calculate that there’s a 97% match between a new song and the songs they usually listen to. However, displaying “97% match” next to the new song as an attribution doesn’t communicate enough information to help people make a choice. In contrast, providing an attribution that clearly identifies the behavior — such as “Because you listen to pop music” — can be more actionable." }, { "type": "paragraph", "text": "In situations where attributions aren’t helpful, consider ranking or ordering the results in a way that implies confidence levels. If you must display confidence directly, consider expressing it in terms of semantic categories. For example, a feature that predicts travel prices might replace ranges of confidence numbers with categories like “high chance” and “low chance” to give context to the values and help people understand and compare the results." }, { "type": "paragraph", "text": "In scenarios where people expect statistical or numerical information, display confidence values that help them interpret the results. For example, weather predictions, sports statistics, and polling numbers are often accompanied by specific values that express the accuracy of the data as an interval or a percentage." }, { "type": "paragraph", "text": "Whenever possible, help people make decisions by conveying confidence in terms of actionable suggestions. Understanding people’s goals is key to expressing confidence in ways that help them make decisions. For example, if your feature predicts when an item will be at its lowest price, you know that people want to optimize how they spend their time and money. For a feature like this, displaying percentages or other numerical confidence values would be less valuable than providing actionable suggestions like “This is a good time to buy,” or “Consider waiting for a better price.”" }, { "type": "paragraph", "text": "Consider changing how you present results based on different confidence thresholds. If high or low levels of confidence have a meaningful impact on the ways people can experience the results, it’s a good idea to adapt your presentation accordingly. For example, when confidence is high, the face recognition feature in Photos simply displays the photos that contain a specific person, but when confidence is lower, the feature asks people to confirm whether the photos contain the person before showing more." }, { "type": "paragraph", "text": "When you know that confidence values correspond to result quality, you generally want to avoid showing results when confidence is low. Especially when a feature is proactive and can make unbidden suggestions, poor results can cause people to be annoyed and even lose trust in the feature. For suggestions and proactive features, it’s a good idea to set a confidence threshold below which you don’t offer results." } ] }, { "heading": "Attribution", "level": 2, "content": [ { "type": "paragraph", "text": "An attribution expresses the underlying basis or rationale for a result, without explaining exactly how a model works. Depending on the design of your app, you might want to use attributions to impart transparency and give people insight into your results. For example, if your app suggests books for people to read, you might use an attribution like “Because you’ve read mysteries” when you suggest books in the “thrillers” category." }, { "type": "paragraph", "text": "To help you decide whether to include attributions in your app, consider how you want them to affect people. For example, you might want attributions to:" }, { "type": "list", "items": [ "Encourage people to change what they do in your app", "Minimize the impact of mistakes", "Help people build a mental model of your feature", "Promote trust in your app over time" ] }, { "type": "paragraph", "text": "Consider using attributions to help people distinguish among results. For example, if you present a set of results as multiple options, including attributions can help people choose an option based on their understanding of the premise that led to it, such as “New books by authors you’ve read.”" }, { "type": "paragraph", "text": "Avoid being too specific or too general. Overly specific attributions can make people feel like they have to do additional work to interpret the results, whereas overly general attributions typically don’t provide useful information. In apps that make content recommendations, general attributions can make people feel like your app is not treating them as individuals, but overly specific attributions can make people think that your app is watching them too closely. The best attributions strike a balance between these extremes." }, { "type": "paragraph", "text": "Keep attributions factual and based on objective analysis. To be useful, an attribution needs to help people reason about a result; you don’t want to provoke an emotional response. Don’t provide an attribution that implies understanding or judgment of people’s emotions, preferences, or beliefs. For example, an app that recommends new content to people can use an attribution like “Because you’ve read nonfiction” instead of an attribution like “Because you love nonfiction.”" }, { "type": "paragraph", "text": "In general, avoid technical or statistical jargon. In most situations, using percentages, statistics, and other technical jargon doesn’t help people assess the results you provide. The exception to this is when the result itself is of a statistical or technical nature, such as information in the areas of weather, sports, polling and election results, or scientific data." } ] }, { "heading": "Limitations", "level": 2, "content": [ { "type": "paragraph", "text": "Every feature — whether it’s based on machine learning or not — has certain limitations to what it can deliver. In general, there are two types of limitations: things a feature can’t do well and things a feature can’t do at all. When there’s a mismatch between people’s expectations about a feature and what the feature can actually accomplish, a limitation can seem like a defect. For example, people might expect:" }, { "type": "list", "items": [ "Photos to perform a search that covers every category they can imagine", "Siri to respond to queries that aren’t well defined, like “What is the meaning of life?”", "FaceID to work from every angle" ] }, { "type": "paragraph", "text": "An important part of the design process is to identify the scenarios where limitations impact the user experience and design ways to help people work with them. For example:" }, { "type": "list", "items": [ "Set people’s expectations before they use the feature.", "Show people how to get the best results while they’re using the feature.", "When inferior results occur, explain why so that people can understand the feature better." ] }, { "type": "paragraph", "text": "Help people establish realistic expectations. When a limitation may have a serious effect on user experience but happens rarely, consider making people aware of the limitation before they use your app or feature. You might describe the limitation in marketing materials or within the feature’s context so that people can decide how they want to rely on the feature. If the effects of a limitation aren’t serious, you can help set people’s expectations by providing attributions." }, { "type": "paragraph", "text": "Demonstrate how to get the best results. If you don’t provide guidance for using a feature, people may assume it’ll do everything they want. When you proactively show people how to get good results, you help them benefit from the feature and establish a more accurate mental model of the feature’s capabilities. There are many ways to show people the best ways to use a feature, such as:" }, { "type": "list", "items": [ "Use placeholder text to suggest input. In Photos, the search bar displays the text “Photos, People, Places…” to help people understand what they can search for before they begin typing. Photos also displays a description of how it scans the photo library to offer search suggestions.", "As people interact with the feature, provide feedback on their actions to guide them towards a result without overwhelming them. For example, while people are interacting with Animoji, the feature responds to current conditions and suggests how people can improve their results by adjusting the lighting or moving closer to the camera.", "Suggest alternative ways to accomplish the goal instead of showing no results. To do this successfully, you need to understand the goal well enough to suggest alternatives that make sense. For example, if people ask Siri to set a timer on a Mac, Siri suggests setting a reminder instead, because timers aren’t available in macOS. This suggestion makes sense because people’s goal is to receive an alert at a certain time." ] }, { "type": "paragraph", "text": "Explain how limitations can cause unsatisfactory results. People can get frustrated when it seems that your feature works intermittently. Ideally, your feature can recognize and describe the reasons for poor results to make people aware of the limitations and help them to adjust their expectations. For example, Animoji tells people that it doesn’t work well in the dark." }, { "type": "paragraph", "text": "Consider telling people when limitations are resolved. When people use a feature frequently, they learn to avoid the interactions that fail because of the feature’s limitations. When you update your app to remove a limitation, you might want to notify people so that they can adjust their mental model of your feature and return to interactions they’d previously avoided." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Generative AI" }, { "type": "paragraph", "text": "Privacy" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Intelligence and machine learning" }, { "type": "paragraph", "text": "Create ML" }, { "type": "paragraph", "text": "Core ML" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "October 24, 2023", "Added art to Corrections section." ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Generative AI", "url": "/design/human-interface-guidelines/generative-ai" }, { "title": "Planning your design", "url": "/design/human-interface-guidelines/machine-learning#Planning-your-design" }, { "title": "role", "url": "/design/human-interface-guidelines/machine-learning#The-role-of-machine-learning-in-your-app" }, { "title": "Critical or complementary", "url": "/design/human-interface-guidelines/machine-learning#Critical-or-complementary" }, { "title": "Private or public", "url": "/design/human-interface-guidelines/machine-learning#Private-or-public" }, { "title": "Proactive or reactive", "url": "/design/human-interface-guidelines/machine-learning#Proactive-or-reactive" }, { "title": "Visible or invisible", "url": "/design/human-interface-guidelines/machine-learning#Visible-or-invisible" }, { "title": "Dynamic or static", "url": "/design/human-interface-guidelines/machine-learning#Dynamic-or-static" }, { "title": "calibration", "url": "/design/human-interface-guidelines/machine-learning#Calibration" }, { "title": "implicit", "url": "/design/human-interface-guidelines/machine-learning#Implicit-feedback" }, { "title": "explicit", "url": "/design/human-interface-guidelines/machine-learning#Explicit-feedback" }, { "title": "multiple options", "url": "/design/human-interface-guidelines/machine-learning#Multiple-options" }, { "title": "Corrections", "url": "/design/human-interface-guidelines/machine-learning#Corrections" }, { "title": "Mistakes", "url": "/design/human-interface-guidelines/machine-learning#Mistakes" }, { "title": "Limitations", "url": "/design/human-interface-guidelines/machine-learning#Limitations" }, { "title": "Attribution", "url": "/design/human-interface-guidelines/machine-learning#Attribution" }, { "title": "Confidence", "url": "/design/human-interface-guidelines/machine-learning#Confidence" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/machine-learning#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/machine-learning#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/machine-learning#Related" }, { "title": "Privacy", "url": "/design/human-interface-guidelines/privacy" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/machine-learning#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/machine-learning#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/machine-learning#Change-log" } ], "image_count": 0 }, { "title": "Maps", "url": "https://developer.apple.com/design/human-interface-guidelines/maps", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "A map uses a familiar interface that supports much of the same functionality as the system-provided Maps app, such as zooming, panning, and rotation. A map can also include annotations and overlays and show routing information, and you can configure it to use a standard graphical view, a satellite image-based view, or a view that’s a hybrid of both." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "In general, make your map interactive. People expect to be able to zoom, pan, and otherwise interact with maps in familiar ways. Noninteractive elements that obscure the map can interfere with people’s expectations for how maps behave." }, { "type": "paragraph", "text": "Pick a map emphasis style that suits the needs of your app. There are two emphasis styles to choose from:" }, { "type": "list", "items": [ "The default style presents a version of the map with fully saturated colors, and is a good option for most standard map applications without a lot of custom elements. This style is also useful for keeping visual alignment between your map and the Maps app, in situations when people might switch between them.", "The muted style, by contrast, presents a desaturated version of the map. This style is great if you have a lot of information-rich content that you want to stand out against the map." ] }, { "type": "paragraph", "text": "Default style" }, { "type": "paragraph", "text": "Muted style" }, { "type": "paragraph", "text": "For developer guidance, see MKStandardMapConfiguration.EmphasisStyle." }, { "type": "paragraph", "text": "Help people find places in your map. Consider offering a search feature combined with a way to filter locations by category. The search field for a shopping mall map, for example, might include filters that make it easy to find common store types, like clothing, housewares, electronics, jewelry, and toys." }, { "type": "paragraph", "text": "Clearly identify elements that people select. When someone selects a specific area or other element on the map, use distinct styling like an outline and color variation to call attention to the selection." }, { "type": "paragraph", "text": "Cluster overlapping points of interest to improve map legibility. A cluster uses a single pin to represent multiple points of interest within close proximity. As people zoom in on a map, clusters expand to progressively reveal individual points of interest." }, { "type": "paragraph", "text": "Points of interest in a cluster" }, { "type": "paragraph", "text": "Individual points of interest when zoomed in" }, { "type": "paragraph", "text": "Help people see the Apple logo and legal link. It’s fine when parts of your interface temporarily cover the logo and link, but don’t cover these elements all the time. Follow these guidelines to help keep the Apple logo and legal link visible:" }, { "type": "list", "items": [ "Use adequate padding to separate the logo and link from the map boundaries and your custom controls. For example, it works well to use 7 points of padding on the sides of the elements and 10 points above and below them.", "Avoid causing the logo and link to move with your interface. It’s best when the Apple logo and legal link appear to be fixed to the map.", "If your custom interface can move relative to the map, use the lowest position of the custom element to determine the placement of the logo and link. For example, if your app lets people pull up a custom card from the bottom of the screen, place the Apple logo and legal link 10 points above the lowest resting position of the card." ] }, { "type": "note", "text": "NoteThe Apple logo and legal link aren’t shown on maps that are smaller than 200x100 pixels." } ] }, { "heading": "Custom information", "level": 2, "content": [ { "type": "paragraph", "text": "Use annotations that match the visual style of your app. Annotations identify custom points of interest on your map. The default annotation marker has a red tint and a white pin icon. You can change the tint to match the color scheme of your app. You can also change the icon to a string or image, like a logo. An icon string can contain any characters, including Unicode characters, but keep it to two to three characters in length for readability. For developer guidance, see MKAnnotationView." }, { "type": "paragraph", "text": "If you want to display custom information that’s related to standard map features, consider making them independently selectable. When you support selectable map features, the system treats Apple-provided features (including points of interest, territories, and physical features) independently from other annotations that you add. You can configure custom appearances and information to represent these features when people select them. For developer guidance, see MKMapFeatureOptions." }, { "type": "paragraph", "text": "Use overlays to define map areas with a specific relationship to your content." }, { "type": "list", "items": [ "Above roads, the default level, places the overlay above roads but below buildings, trees, and other features. This is great for situations where you want people to have an idea of what’s below the overlay, while still clearly understanding that it’s a defined space.", "Above labels places the overlay above both roads and labels, hiding everything beneath it. This is useful for content that you want to be fully abstracted from the features of the map, or when you want to hide areas of the map that aren’t relevant." ] }, { "type": "paragraph", "text": "For developer guidance, see Displaying overlays on a map and MKOverlayLevel." }, { "type": "paragraph", "text": "Make sure there’s enough contrast between custom controls and the map. Insufficient contrast makes controls hard to see and can cause them to blend in with the map. Consider using a thin stroke or light drop shadow to help a custom control stand out, or applying blend modes to the map area to increase its contrast with the controls atop it." } ] }, { "heading": "Place cards", "level": 2, "content": [ { "type": "paragraph", "text": "Place cards display rich place information in your app or website, such as operating hours, phone numbers, addresses, and more. This enables you to provide structured and up-to-date information for places that you specify, and add depth to search results." } ] }, { "heading": "Displaying place cards in a map", "level": 3, "content": [ { "type": "paragraph", "text": "You can present a place card that appears directly in your map anytime someone selects a place. This is a great way to provide place information in a map with multiple places that you specify, like a map of bookstores that an author plans to visit on their book signing tour. For developer guidance, see mapItemDetailSelectionAccessory(_:), mapView(_:selectionAccessoryFor:), and selectionAccessory." }, { "type": "paragraph", "text": "You can also display place cards for other places on a map, such as points of interest, territories, and physical features, to provide valuable context to people about nearby places. For developer guidance, see mapFeatureSelectionAccessory(_:), mapView(_:selectionAccessoryFor:), and selectableMapFeatureSelectionAccessory." }, { "type": "note", "text": "Developer noteIn websites, you can embed a custom map that displays a place card by default for a single place that you specify. For developer guidance, see Displaying place information using the Maps Embed API." }, { "type": "paragraph", "text": "The system defines several place card styles, which specify the size, appearance, and information included in a place card." }, { "type": "list", "items": [ "The automatic style lets the system determine the place card style based on the size of your map view.", "The callout style displays a place card in a popover style next to the selected place. You can further specify the style of a callout — the full callout style displays a large, detailed place card, and the compact callout style displays a space-saving, more concise place card. If you don’t specify a callout style, the system defaults to the automatic callout style, which determines the callout style based on your map’s view size.", "The caption style displays an “Open in Apple Maps” link.", "The sheet style displays a place card in a sheet." ] }, { "type": "paragraph", "text": "For developer guidance, see MapItemDetailSelectionAccessoryStyle, MKSelectionAccessory.MapItemDetailPresentationStyle, and PlaceSelectionAccessoryStyle." }, { "type": "paragraph", "text": "Full callout style place cards appear differently depending on a person’s device. The system presents the full callout style place card in a popover style in iPadOS and macOS, and as a sheet in iOS." }, { "type": "paragraph", "text": "Consider your map presentation when choosing a style. The full callout style place card offers people the richest experience, presenting them with the most information about a place directly in your map. However, be sure to choose a place card style that fits in the context of your map. For example, if your app displays a small map with many annotations, consider using the compact callout style for a space-saving presentation that shows place information while maintaining the context of the other places that you specify in your map." }, { "type": "paragraph", "text": "Make sure your place card looks great on different devices and window sizes. If you choose to specify a style, ensure that the content in your place card remains viewable on different devices and as window sizes change. For full callout style place cards, you can set a minimum width to prevent text from overflowing on smaller devices." }, { "type": "paragraph", "text": "Avoid duplicating information. Consider what information you already display in your app or website when you choose a place card style. For example, the full callout style place card might display information that your app already shows. In this case, the compact callout or caption style might be a better complement." }, { "type": "paragraph", "text": "Keep the location on your map visible when displaying a place card. This helps people maintain a sense of where the location is on your map while getting detailed place information. You can set an offset distance for your place card and point it to the selected location. For developer guidance, see offset(_:), accessoryOffset, and selectionAccessoryOffset." } ] }, { "heading": "Adding place cards outside of a map", "level": 3, "content": [ { "type": "paragraph", "text": "You can also display place information outside of a map in your app or website. For example, you might want to display a list of places rather than a map, like in search results or a store locator, and present a place card when people select one. For developer guidance, see mapItemDetailSelectionAccessory(_:), mapItemDetail(_:), and PlaceDetail." }, { "type": "important", "text": "ImportantIf you don’t display a place card directly within a map view, you must include a map in the place card. For developer guidance, see mapItemDetailSheet(item:displaysMap:) and init(mapItem:displaysMap:)." }, { "type": "paragraph", "text": "Use location-related cues in surrounding content to help communicate that people can open a place card. For example, you can display place names and addresses alongside a button for more details to help indicate that people can interact with it to get place information. For a space-efficient design, you can include a map pin icon with a place name to help communicate that people can open a place card." } ] }, { "heading": "Indoor maps", "level": 2, "content": [ { "type": "paragraph", "text": "Apps connected with specific venues like shopping malls and stadiums can design custom interactive maps that help people locate and navigate to indoor points of interest. Indoor maps can include overlays that highlight specific areas, such as rooms, kiosks, and other locations. They can also include text labels, icons, and routes." }, { "type": "paragraph", "text": "Adjust map detail based on the zoom level. Too much detail can cause a map to appear cluttered. Show large areas like rooms and buildings at all zoom levels. Then, progressively add more detailed features and labels as the map is zoomed in. An airport map might show only terminals and gates when zoomed out, but reveal individual stores and restrooms when zoomed in." }, { "type": "paragraph", "text": "Use distinctive styling to differentiate the features of your map. Using color along with icons can help distinguish different types of areas, stores, and services, and make it easy for people to quickly find what they’re looking for." }, { "type": "paragraph", "text": "Offer a floor picker if your venue includes multiple levels. A floor picker lets people quickly jump between floors. If you implement this feature, keep floor numbers concise for simplicity. In most cases, a list of floor numbers — rather than floor names — is sufficient." }, { "type": "paragraph", "text": "Include surrounding areas to provide context. Adjacent streets, playgrounds, and other nearby locations can all help orient people when they use your map. If these areas are noninteractive, use dimming and a distinct color to make them appear supplemental." }, { "type": "paragraph", "text": "Consider supporting navigation between your venue and nearby transit points. Make it easy to enter and exit your venue by offering routing to and from nearby bus stops, train stations, parking lots, garages, and other transit locations. You might also offer a way for people to quickly switch over to Apple Maps for additional navigation options." }, { "type": "paragraph", "text": "Limit scrolling outside of your venue. This can help people avoid getting lost when they swipe too hard on your map. When possible, keep at least part of your indoor map visible onscreen at all times. To help people stay oriented, you may need to adjust the amount of scrolling you permit based on the zoom level." }, { "type": "paragraph", "text": "Design an indoor map that feels like a natural extension of your app. Don’t try to replicate the appearance of Apple Maps. Instead, make sure area overlays, icons, and text match the visual style of your app. For guidance, see Indoor Mapping Data Format." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or visionOS." } ] }, { "heading": "watchOS", "level": 3, "content": [ { "type": "paragraph", "text": "On Apple Watch, maps are static snapshots of geographic locations. Place a map in your interface at design time and show the appropriate region at runtime. The displayed region isn’t interactive; tapping it opens the Maps app on Apple Watch. You can add up to five annotations to a map to highlight points of interest or other relevant information. For developer guidance, see WKInterfaceMap." }, { "type": "paragraph", "text": "Fit the map interface element to the screen. The entire element needs to be visible on the Apple Watch display without requiring scrolling." }, { "type": "paragraph", "text": "Show the smallest region that encompasses the points of interest. The content within a map interface element doesn’t scroll, so all key content must be visible within the displayed region." }, { "type": "paragraph", "text": "For developer guidance, see WKInterfaceMap." } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "MapKit" }, { "type": "paragraph", "text": "MapKit JS" }, { "type": "paragraph", "text": "Indoor Mapping Data Format" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 18, 2024", "Added guidance for place cards and included additional artwork." ], [ "September 12, 2023", "Added artwork." ], [ "September 23, 2022", "Added guidelines for presenting custom information, refined best practices, and consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/maps#Best-practices" }, { "title": "Custom information", "url": "/design/human-interface-guidelines/maps#Custom-information" }, { "title": "Place cards", "url": "/design/human-interface-guidelines/maps#Place-cards" }, { "title": "Displaying place cards in a map", "url": "/design/human-interface-guidelines/maps#Displaying-place-cards-in-a-map" }, { "title": "sheet", "url": "https://developer.apple.com/design/human-interface-guidelines/sheets" }, { "title": "Adding place cards outside of a map", "url": "/design/human-interface-guidelines/maps#Adding-place-cards-outside-of-a-map" }, { "title": "Indoor maps", "url": "/design/human-interface-guidelines/maps#Indoor-maps" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/maps#Platform-considerations" }, { "title": "watchOS", "url": "/design/human-interface-guidelines/maps#watchOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/maps#Resources" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/maps#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/maps#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/maps#Change-log" } ], "image_count": 0 }, { "title": "NFC", "url": "https://developer.apple.com/design/human-interface-guidelines/nfc", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "iOS apps running on supported devices can use NFC scanning to read data from electronic tags attached to real-world objects. For example, a person can scan a toy to connect it with a video game, a shopper can scan an in-store sign to access coupons, or a retail employee can scan products to track inventory." } ] }, { "heading": "In-app tag reading", "level": 2, "content": [ { "type": "paragraph", "text": "An app can support single- or multiple-object scanning when the app is active, and display a scanning sheet whenever people are about to scan something." }, { "type": "paragraph", "text": "Don’t encourage people to make contact with physical objects. To scan a tag, an iOS device must simply be within close proximity of the tag. It doesn’t need to actually touch the tag. Use terms like scan and hold near instead of tap and touch when asking people to scan objects." }, { "type": "paragraph", "text": "Use approachable terminology. Near-field communication may be unfamiliar to some people. To make it approachable, avoid referring to technical, developer-oriented terms like NFC, Core NFC, Near-field communication, and tag. Instead, use friendly, conversational terms that most people will understand." }, { "type": "table", "rows": [ [ "Use", "Don’t use" ], [ "Scan the [object name].", "Scan the NFC tag." ], [ "Hold your iPhone near the [object name] to learn more about it.", "To use NFC scanning, tap your phone to the [object]." ] ] }, { "type": "paragraph", "text": "Provide succinct instructional text for the scanning sheet. Provide a complete sentence, in sentence case, with ending punctuation. Identify the object to scan, and revise the text appropriately for subsequent scans. Keep the text short to avoid truncation." }, { "type": "table", "rows": [ [ "First scan", "Subsequent scans" ], [ "Hold your iPhone near the [object name] to learn more about it.", "Now hold your iPhone near another [object name]." ] ] } ] }, { "heading": "Background tag reading", "level": 2, "content": [ { "type": "paragraph", "text": "Background tag reading lets people scan tags quickly any time, without needing to first open your app and initiate scanning. On devices that support background tag reading, the system automatically looks for nearby compatible tags whenever the screen is illuminated. After detecting and matching a tag with an app, the system shows a notification that the people can tap to send the tag data to the app for processing. Note that background reading isn’t available when an NFC scanning sheet is visible, Wallet or Apple Pay are in use, cameras are in use, the device is in Airplane Mode, and the device is locked after a restart." }, { "type": "paragraph", "text": "Support both background and in-app tag reading. Your app must still provide an in-app way to scan tags, for people with devices that don’t support background tag reading." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Core NFC" } ] } ], "platforms": [], "related": [ { "title": "In-app tag reading", "url": "/design/human-interface-guidelines/nfc#In-app-tag-reading" }, { "title": "Background tag reading", "url": "/design/human-interface-guidelines/nfc#Background-tag-reading" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/nfc#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/nfc#Resources" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/nfc#Developer-documentation" } ], "image_count": 0 }, { "title": "Photo editing", "url": "https://developer.apple.com/design/human-interface-guidelines/photo-editing", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Edits are always saved in the Photos app as new files, safely preserving the original versions." }, { "type": "paragraph", "text": "To access a photo editing extension, a photo must be in edit mode. While in edit mode, tapping the extension icon in the toolbar displays an action menu of available editing extensions. Selecting one displays the extension’s interface in a modal view containing a top toolbar. Dismissing this view confirms and saves the edit, or cancels it and returns to the Photos app." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Confirm cancellation of edits. Editing a photo or video can be time consuming. If someone taps the Cancel button, don’t immediately discard their changes. Ask them to confirm that they really want to cancel, and inform them that any edits will be lost after cancellation. There’s no need to show this confirmation if no edits have been made yet." }, { "type": "paragraph", "text": "Don’t provide a custom top toolbar. Your extension loads within a modal view that already includes a toolbar. Providing a second toolbar is confusing and takes space away from the content being edited." }, { "type": "paragraph", "text": "Let people preview edits. It’s hard to approve an edit if you can’t see what it looks like. Let people see the result of their work before closing your extension and returning to the Photos app." }, { "type": "paragraph", "text": "Use your app icon for your photo editing extension icon. This instills confidence that the extension is in fact provided by your app." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, or macOS. Not supported in tvOS, visionOS, or watchOS." } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "App extensions" }, { "type": "paragraph", "text": "PhotoKit" } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/photo-editing#Best-practices" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/photo-editing#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/photo-editing#Resources" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/photo-editing#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/photo-editing#Videos" } ], "image_count": 0 }, { "title": "ResearchKit", "url": "https://developer.apple.com/design/human-interface-guidelines/researchkit", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "The ResearchKit framework provides predesigned screens and transitions that make it easy to design and build an engaging custom research app. For developer guidance, see Research & Care > ResearchKit." }, { "type": "paragraph", "text": "These guidelines are for informational purposes only and don’t constitute legal advice. Contact an attorney to obtain advice with respect to the development of a research app and any applicable laws." } ] }, { "heading": "Creating the onboarding experience", "level": 2, "content": [ { "type": "paragraph", "text": "When opening a research app for the first time, people encounter a series of screens that introduce them to the study, determine their eligibility to participate, request permission to proceed with the study, and, when appropriate, grant access to personal data. These screens aren’t typically revisited once they’ve been completed, so clarity is essential." }, { "type": "paragraph", "text": "Always display the onboarding screens in the correct order." } ] }, { "heading": "1. Introduction", "level": 3, "content": [ { "type": "paragraph", "text": "Provide an introduction that informs and provides a call to action. Clearly describe the subject and purpose of your study. Also allow existing participants to quickly log in and continue an in-progress study." } ] }, { "heading": "2. Determine eligibility", "level": 3, "content": [ { "type": "paragraph", "text": "Determine eligibility as soon as possible. People don’t need to move on to the consent section if they’re not eligible for the study. Only present eligibility requirements that are necessary for your study. Use simple, straightforward language that describes the requirements, and make it easy to enter information." } ] }, { "heading": "3. Get informed consent", "level": 3, "content": [ { "type": "paragraph", "text": "Make sure participants understand your study before you get their consent. ResearchKit helps you make the consent process concise and friendly, while still allowing you to incorporate into the consent any legal requirements or requirements set by an institutional review board or ethics review board. Make sure that your app complies with the applicable App Store Guidelines, including the consent requirements. Typically, the consent section explains how the study works, ensures that participants understand the study and their responsibilities, and gets the participant’s consent." }, { "type": "paragraph", "text": "Break a long consent form into easily digestible sections. Each section can cover one aspect of the study, such as data gathering, data use, potential benefits, possible risks, time commitment, how to withdraw, and so on. For each section, use simple, straightforward language to provide a high-level overview. If necessary, provide a more detailed explanation of the section that participants can read by tapping a Learn More button. Participants need to be able to view the entire consent form before they agree to participate." }, { "type": "paragraph", "text": "If it makes sense, provide a quiz that tests the participant’s understanding. You might do this for questions the participant would otherwise be asked when obtaining consent in person." }, { "type": "paragraph", "text": "Get the participant’s consent and, if appropriate, some contact information. After agreeing to join the study, participants receive a confirmation dialog, followed by screens in which they provide their signature and contact details. Most research apps email participants a PDF version of the consent form for their records." } ] }, { "heading": "4. Request permission to access data", "level": 3, "content": [ { "type": "paragraph", "text": "Get permission to access the participant’s device or data, and to send notifications. Clearly explain why your research app needs access to location, Health, or other data, and don’t request access to data that isn’t critical to your study. If your app requires it, also ask for permission to send notifications to the participant’s device." } ] }, { "heading": "Conducting research", "level": 2, "content": [ { "type": "paragraph", "text": "To get input from participants, your study might use surveys, active tasks, or a combination of both. Depending on the architecture of your study, participants may interact with each section multiple times or only once." }, { "type": "paragraph", "text": "Create surveys that keep participants engaged. ResearchKit provides many customizable screens you can use in your surveys, and makes it easy to present questions that require different types of answers, such as true or false, multiple choice, dates and times, sliding scales, and open-ended text entry. As you use ResearchKit screens to design a survey, follow these guidelines to provide a great experience:" }, { "type": "list", "items": [ "Tell participants how many questions there are and about how long the survey will take.", "Use one screen per question.", "Show participants their progress in the survey.", "Keep the survey as short as possible. Several short surveys tend to work better than one long survey.", "For questions that require some additional explanation, use the standard font for the question and a slightly smaller font for the explanatory text.", "Tell participants when the survey is complete." ] }, { "type": "paragraph", "text": "Make active tasks easy to understand. An active task requires the participant to engage in an activity, such as speaking into the microphone, tapping fingers on the screen, walking, or performing a memory test. Follow these guidelines to encourage participants to perform an active task and give them the best chance of success:" }, { "type": "list", "items": [ "Describe how to perform the task using clear, simple language.", "Explain any requirements, such as if the task must be performed at a particular time or under specific circumstances.", "Make sure participants can tell when the task is complete." ] } ] }, { "heading": "Managing personal information and providing encouragement", "level": 2, "content": [ { "type": "paragraph", "text": "ResearchKit offers a profile screen you can use to let participants manage personal information while they’re in your research app. It’s also a good idea to design a custom screen that motivates people and gives them a way to track progress in the study. Ideally, both screens are accessible at all times in your app." }, { "type": "paragraph", "text": "Use a profile to help participants manage personal data related to your study. A profile screen can let people edit data that might change during the course of the study — such as weight or sleep habits — and remind them of upcoming activities. A profile screen can also provide an easy way to leave a study and view important information, such as the consent document and privacy policy." }, { "type": "paragraph", "text": "Use a dashboard to show progress and motivate participants to continue. If appropriate for your study, use a dashboard to provide encouraging feedback, such as daily progress, weekly assessments, results from specific activities, and even results that compare the participant’s results with aggregated results from others in the study." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Research & Care > ResearchKit" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Research & Care > Developers" }, { "type": "paragraph", "text": "Protecting user privacy — HealthKit" }, { "type": "paragraph", "text": "ResearchKit GitHub project" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 12, 2023", "Updated artwork." ] ] } ] } ], "platforms": [], "related": [ { "title": "Creating the onboarding experience", "url": "/design/human-interface-guidelines/researchkit#Creating-the-onboarding-experience" }, { "title": "1. Introduction", "url": "/design/human-interface-guidelines/researchkit#1-Introduction" }, { "title": "2. Determine eligibility", "url": "/design/human-interface-guidelines/researchkit#2-Determine-eligibility" }, { "title": "3. Get informed consent", "url": "/design/human-interface-guidelines/researchkit#3-Get-informed-consent" }, { "title": "4. Request permission to access data", "url": "/design/human-interface-guidelines/researchkit#4-Request-permission-to-access-data" }, { "title": "Conducting research", "url": "/design/human-interface-guidelines/researchkit#Conducting-research" }, { "title": "Managing personal information and providing encouragement", "url": "/design/human-interface-guidelines/researchkit#Managing-personal-information-and-providing-encouragement" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/researchkit#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/researchkit#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/researchkit#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/researchkit#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/researchkit#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/researchkit#Change-log" } ], "image_count": 0 }, { "title": "SharePlay", "url": "https://developer.apple.com/design/human-interface-guidelines/shareplay", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "The system synchronizes app playback on all participating devices to support seamless media and content sharing that lets everyone enjoy the experience simultaneously. In visionOS, SharePlay helps people enjoy these experiences while they’re together in the same virtual space." }, { "type": "paragraph", "text": "When someone shares content during a FaceTime call, the system asks each participant to launch the app to begin the experience. If people don’t have the app installed, the SharePlay alert encourages them to download it from the App Store. If you make the platform-specific versions of your app available as a Universal Purchase, people can make one purchase and use your app and their in-app purchases across all the platforms you support." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Let people know that you support SharePlay. People often expect media playback experiences to be shareable, so indicate this capability in your interface. For example, you can use the shareplay SF Symbol to identify the content or experiences in your app that support SharePlay." }, { "type": "paragraph", "text": "If part of your app requires a subscription, consider ways to help nonsubscriber participants quickly join a group activity. For example, you might offer temporary or provisional access to nonsubscribers or let an existing subscriber send a one-time pass to a friend. To make it easy for family members to share your content in a SharePlay experience, you can support Family Sharing. If people can start a subscription during a SharePlay experience, present a streamlined version of your sign-up flow so they can join the activity without making others wait. For guidance, see Auto-renewable subscriptions." }, { "type": "paragraph", "text": "Support Picture in Picture (PiP) when possible. On iPhone and iPad, people can open a shared video in a PiP window. On a Mac, a shared video opens in a background window that people can move into the foreground when they want to watch." }, { "type": "paragraph", "text": "Use the term SharePlay correctly. You can use SharePlay as a noun — as in “Join SharePlay” — and also as a verb when describing a direct action in your interface. For example, in a button or sheet that lets people share a movie-viewing activity, you can use a phrase like “SharePlay Movie.” Avoid using an adjective with SharePlay; for example, in your visionOS app, don’t add terms like virtual or spatial. Avoid changing the term SharePlay in any way; for example, don’t use variations like SharePlayed, SharePlays, or SharePlaying." } ] }, { "heading": "Sharing activities", "level": 2, "content": [ { "type": "paragraph", "text": "An activity is an app-defined type of shareable experience. For example, an app that lets people view videos might define a separate activity for viewing each type of content — like movies, TV shows, and uploaded videos — and display a different description for each activity. You can define as many different activities as make sense in your app. For developer guidance, see Defining your app’s SharePlay activities." }, { "type": "paragraph", "text": "Briefly describe each activity. When people receive an invitation to participate in an activity, your description helps them understand the experience they’re about to share. For example, a video-viewing app might associate its descriptive movie view with a movie-viewing activity. In this case, the descriptive view might display a movie’s title, a plot summary, and a poster image. Write a simple, meaningful description that’s short enough to avoid truncation." }, { "type": "paragraph", "text": "Make it easy to start sharing an activity. If there’s no session available when people start a shareable activity, you can present UI that lets them start a group activity. In response, the system asks people if they want to share or continue the experience solo." }, { "type": "paragraph", "text": "Help people prepare to join a session before displaying the activity. For example, if people must log in, download content, or make a payment before they can participate, display views that help them perform these tasks before showing the activity UI. Make these tasks as simple and effortless as possible so people can join the group activity quickly." }, { "type": "paragraph", "text": "When possible, defer app tasks that might delay a shared activity. For example, if your app needs to know a participant’s profile, consider asking for this information at a convenient time, like when playback pauses or finishes." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "People expect most visionOS apps to support SharePlay. While wearing Apple Vision Pro, people choose the Spatial option in FaceTime to share content and activities with others." }, { "type": "paragraph", "text": "In a shared activity, FaceTime can show representations of other participants — called spatial Personas — within each wearer’s space, making everyone feel like they’re sharing the same experience in the same place. During a shared experience in FaceTime, people can interact with each other in natural ways through their spatial Personas. For example, people can speak or gesture directly to others, tell when someone is paying attention to them, and know which person is using a shared tool or resource." }, { "type": "paragraph", "text": "visionOS uses the concept of shared context to describe the characteristics of a shared activity that help people feel physically present with others while connecting over the same content. A shared context helps give people confidence that they’re experiencing the same thing as everyone else." }, { "type": "paragraph", "text": "When people feel that they’re truly sharing an experience, social dynamics can encourage authentic, intuitive interactions. For example, people can communicate verbally and nonverbally to make plans, take turns, and share resources." }, { "type": "note", "text": "NoteDuring a shared activity, the system helps preserve people’s privacy by obscuring some visual details about wearers. In addition, a person can adjust their spatial Persona if they want. Although the system can place spatial Personas shoulder to shoulder and it supports shared gestures like a handshake or “high five,” spatial Personas remain apart." }, { "type": "paragraph", "text": "Choose the spatial Persona template that suits your shared activity. When you design a shared activity, you can use a spatial Persona template to specify a layout for arranging spatial Personas in the shared activity space. The system provides three spatial Persona templates: side-by-side, surround, and conversational." }, { "type": "paragraph", "text": "The side-by-side template places participants next to each other along a curved line segment, all facing the shared content. The side-by-side template gives everyone a great view of the content, making it a good choice for helping people watch media together. Because people aren’t facing each other in this arrangement, the side-by-side template can encourage less nonverbal interaction than other spatial Persona templates." }, { "type": "paragraph", "text": "The system-applied surround template arranges participants all the way around the shared content in the center. This spatial Persona template works especially well when the content is 3D, because each participant views it from a different angle. In the surround template, participants face each other as if they were grouped around a table, promoting both verbal and nonverbal interactions." }, { "type": "paragraph", "text": "The conversational template also groups participants around a center point, but places your content along the circle, not at its center. Because of this position, not everyone has the same view of your content, and it might not be convenient for everyone to interact with it. Consider using the conversational arrangement if your experience is more about people being together while your app performs a task in the background like playing music." }, { "type": "paragraph", "text": "For developer guidance, see SystemCoordinator and SpatialTemplatePreference." }, { "type": "paragraph", "text": "Be prepared to launch directly into your shared activity. When one person shares your activity with others on a FaceTime call, the system minimizes friction by automatically launching your app for everyone. In this scenario, you want to avoid displaying any windows that aren’t related to the shared activity. For example, if people need to sign in before joining the activity, be sure to present this task in an autodismissible window that disappears as soon as people finish providing the required input." }, { "type": "paragraph", "text": "Help people enter a shared activity together, but don’t force them. When one participant changes their level of immersion, the system tells you so you can synchronize the experience for everyone. Before synchronizing, check whether changing a person’s level of immersion would disrupt their current task; if it would, offer them the choice to join the updated experience. For example, if someone is editing content in an unshared window, you might present an alert that lets them choose to transition. For guidance, see Immersive experiences." }, { "type": "paragraph", "text": "Smoothly update a shared activity when new participants join. When someone joins an in-progress activity, you need to integrate them without disrupting the experience for everyone else. For example, it’s important to update shared immersive content to keep all participants synchronized. Also, consider designing ways to accommodate up to five participants in your arrangement, updating their positions as necessary." } ] }, { "heading": "Maintaining a shared context", "level": 4, "content": [ { "type": "paragraph", "text": "When your shared activity runs in a Full Space, the system helps your app maintain a shared context by using a single coordinate system to arrange your content and all participants, automatically synchronizing the size, position, and orientation of your app for each person. You’re responsible for displaying objects, playing sounds, and supporting interactions in ways that enhance the feeling of sharing the experience." }, { "type": "paragraph", "text": "Make sure everyone views the same state of your app. If your app has more than one state — such as a media app that provides both minimal and theater-like viewing modes — you need to avoid letting different participants view different states, because doing so can diminish people’s sense of being together in a shared space. The exception to this is when someone needs to temporarily exit a shared activity; for guidance, see Adjusting a shared context." }, { "type": "paragraph", "text": "Use Spatial Audio to enrich your shared activity. Playing Spatial Audio can help you strengthen the realism of the shared experience. For guidance, see Playing audio." }, { "type": "paragraph", "text": "When possible, let people discover natural, social solutions to confusions or conflicts that might arise during a shared experience. For example, if only one participant at a time can use a virtual tool, avoid displaying UI, like tool-use controls or notifications, and instead let people speak or gesture to the group when they want to use the tool. If conflicts can arise during your shared activity — for example, if multiple people try to change the same content at the same time — consider implementing a simple rule, like last change wins, and letting people use the rule to define behavior that’s acceptable to the group." }, { "type": "paragraph", "text": "Help people keep their private and shared content separate. By default, the system clearly differentiates a shared window from windows that aren’t shared. For example, when people use Music to listen together, the shared Music window appears as a new window for everyone, while any individual’s open library window remains separate and unshared. If your app can open multiple windows, help people share the one they want and make it easy for them to distinguish shared from unshared windows. If possible, also let people drag content they want to share from a private window to a shared one." }, { "type": "paragraph", "text": "Content in a TV window is private by default." }, { "type": "paragraph", "text": "People can select the Share button to choose whether, and with whom, to share the viewing experience." }, { "type": "paragraph", "text": "When sharing, the app clearly communicates the shared state." } ] }, { "heading": "Adjusting a shared context", "level": 4, "content": [ { "type": "paragraph", "text": "Sometimes, it makes sense to adjust the shared context of a shared activity so each participant can customize their experience, such as for comfort or accessibility. In other situations, strictly maintaining a shared context might decrease people’s enjoyment of the experience. For example, when content has only one ideal viewing angle, each participant might need their own." }, { "type": "paragraph", "text": "Let people personalize their experience without changing the experience for others. For example, people might need to adjust various settings, like volume or subtitles, to make views and interactions accessible or make themselves more comfortable." }, { "type": "paragraph", "text": "When sharing, two people watching the same video can choose separately whether to turn subtitles on or off." }, { "type": "paragraph", "text": "Consider when to give each participant a unique view of the shared content. Some content looks best when people view it from a specific perspective. For example, people can share a Spatial Capture in a standard window with other people’s spatial Personas visible around it. However, to perceive the depth in a Spatial Capture, each person needs to view it from the right angle. In this scenario, a person could temporarily transition to a Full Space that hides other participants and ensures the right viewing angle for them, even while everyone else continues to view the standard window and each other. If it makes sense to provide per-person versions of your shared content, be sure to continue synchronizing people’s positions and your app context to maintain the shared experience." }, { "type": "paragraph", "text": "Make it easy for people to exit and rejoin a shared activity. Sometimes, people need to perform an unrelated task in your app or a different one, or engage with their physical surroundings. When this happens, you need to present a control or other component that lets people quickly rejoin the shared activity. In addition, you might want to continue displaying the shared content so people can stay informed about the ongoing shared experience while they’re hiding their spatial Persona." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Auto-renewable subscriptions" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Group Activities" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "December 5, 2023", "Added artwork for visionOS." ], [ "June 21, 2023", "Updated to include guidance for visionOS." ], [ "December 19, 2022", "Clarified guidance for helping nonsubscribers join a group activity." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/shareplay#Best-practices" }, { "title": "Family Sharing", "url": "https://developer.apple.com/design/human-interface-guidelines/in-app-purchase#Supporting-Family-Sharing" }, { "title": "Auto-renewable subscriptions", "url": "/design/human-interface-guidelines/in-app-purchase#Auto-renewable-subscriptions" }, { "title": "Sharing activities", "url": "/design/human-interface-guidelines/shareplay#Sharing-activities" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/shareplay#Platform-considerations" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/shareplay#visionOS" }, { "title": "Immersive experiences", "url": "/design/human-interface-guidelines/immersive-experiences" }, { "title": "Maintaining a shared context", "url": "/design/human-interface-guidelines/shareplay#Maintaining-a-shared-context" }, { "title": "Adjusting a shared context", "url": "/design/human-interface-guidelines/shareplay#Adjusting-a-shared-context" }, { "title": "Playing audio", "url": "/design/human-interface-guidelines/playing-audio" }, { "title": "Resources", "url": "/design/human-interface-guidelines/shareplay#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/shareplay#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/shareplay#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/shareplay#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/shareplay#Change-log" } ], "image_count": 0 }, { "title": "ShazamKit", "url": "https://developer.apple.com/design/human-interface-guidelines/shazamkit", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "You can use ShazamKit to provide features like:" }, { "type": "list", "items": [ "Enhancing experiences with graphics that correspond with the genre of currently playing music", "Making media content accessible to people with hearing disabilities by providing closed captions or sign language that syncs with the audio", "Synchronizing in-app experiences with virtual content in contexts like online learning and retail" ] }, { "type": "paragraph", "text": "If you need the device microphone to get audio samples for your app to recognize, you must request access to it. As with all types of permission requests, it’s important to help people understand why you’re asking for access. For guidance, see Privacy." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "After you receive permission to access the microphone for features that use ShazamKit, follow these guidelines." }, { "type": "paragraph", "text": "Stop recording as soon as possible. When people allow your app to record audio for recognition, they don’t expect the microphone to stay on. To help preserve privacy, only record for as long as it takes to get the sample you need." }, { "type": "paragraph", "text": "Let people opt in to storing your app’s recognized songs to their iCloud library. If your app can store recognized songs to iCloud, give people a way to first approve this action. Even though both the Music Recognition control and the Shazam app show your app as the source of the recognized song, people appreciate having control over which apps can store content in their library." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "ShazamKit" } ] } ], "platforms": [], "related": [ { "title": "Privacy", "url": "/design/human-interface-guidelines/privacy" }, { "title": "Best practices", "url": "/design/human-interface-guidelines/shazamkit#Best-practices" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/shazamkit#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/shazamkit#Resources" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/shazamkit#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/shazamkit#Videos" } ], "image_count": 0 }, { "title": "Sign in with Apple", "url": "https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "Supporting Sign in with Apple lets people use the Apple Account they already have to sign in or sign up, and skip filling out forms, verifying email addresses, and choosing passwords. In cases where you choose to ask for a name and email address, people have the option to share a unique, random email address that automatically relays messages to their personal email address. For developer guidance, see Authentication Services." }, { "type": "paragraph", "text": "You can offer Sign in with Apple in every version of your app or website across all platforms — including non-Apple platforms." }, { "type": "paragraph", "text": "Sign in with Apple makes it easy for people to authenticate with Face ID, Touch ID, or Optic ID and has two-factor authentication built in for an added layer of security. Apple doesn’t use Sign in with Apple to profile people or their activity in apps." } ] }, { "heading": "Offering Sign in with Apple", "level": 2, "content": [ { "type": "paragraph", "text": "Follow these guidelines to offer Sign in with Apple when it’s most convenient for people." }, { "type": "paragraph", "text": "Ask people to sign in only in exchange for value. People need to understand why you’re asking them to sign in, so it can work well to display a brief, approachable description of sign-in benefits. For example, you might want to tell people that signing in lets them personalize the app experience, access additional features, or synchronize data." }, { "type": "paragraph", "text": "Delay sign-in as long as possible. People often abandon apps when they’re forced to sign in before doing anything useful. Give them a chance to familiarize themselves with your app before making a commitment. For example, a live-streaming app could let people explore available content before signing in to stream something." }, { "type": "paragraph", "text": "If you require an account, ask people to set it up before offering any sign-in options. Start by explaining the reasons for requiring an account. Then, after people complete account setup, let them choose a convenient way to sign in to their new account by offering Sign in with Apple and any other sign-in methods you support." }, { "type": "paragraph", "text": "Consider letting people link an existing account to Sign in with Apple. When you support this type of linking, people can get the convenience of using Sign in with Apple while maintaining access to the information in an account they’ve already set up. You can offer account linking before or after people sign in to their existing account. For example:" }, { "type": "list", "items": [ "If people share an email address through Sign in with Apple and it matches the address in an existing account, you can suggest that they link Sign in with Apple to that account.", "If people used an existing user name and password to sign in, you can display an account-linking suggestion in their account’s settings view or another logical place." ] }, { "type": "paragraph", "text": "In a commerce app, wait until after people make a purchase before asking them to create an account. If you support a guest checkout system, give people a quick way to create an account after the transaction completes. For example, if you support Apple Pay, let people create an account on the order confirmation page. In cases where people have already provided their name and email address during the Apple Pay transaction, you don’t need to ask for this information." }, { "type": "paragraph", "text": "As soon as Sign in with Apple completes, welcome people to their new account. Help people use their new account right away; don’t delay the experience by asking for information that isn’t required." }, { "type": "paragraph", "text": "Indicate when people are currently signed in. You can help people confirm their sign-in method by displaying a phrase like “Using Sign in with Apple” in places like a settings or account interface." } ] }, { "heading": "Collecting data", "level": 2, "content": [ { "type": "paragraph", "text": "People appreciate Sign in with Apple for its privacy and convenience. Although some apps or websites may require additional information — such as a date of birth or a region of residence — it’s essential to minimize your requests for data as people set up an account. Build on the trust that people have in Sign in with Apple by describing why you need additional data and clearly displaying the data you receive." }, { "type": "paragraph", "text": "Clarify whether the additional data you request is required or just recommended. If the data is legally or contractually required — such as an agreement to terms of service, country or region of residence, birth date, or information required by a region’s real-identity laws — make sure people understand that they must supply the additional information to complete the setup of their account. If additional data isn’t required but can improve the user experience, make sure people know the request is optional and help them understand the benefits of providing the information." }, { "type": "paragraph", "text": "Don’t ask people to supply a password. A key benefit of Sign in with Apple is that people don’t have to create and memorize additional passwords. Unless people have stopped using Sign in with Apple with your app or website, don’t ask for a password." }, { "type": "paragraph", "text": "Avoid asking for a personal email address when people supply a private relay address. Using Sign in with Apple, people can choose to share a private relay address that automatically forwards messages to their verified personal email account. It’s essential to respect this choice and avoid overriding it by asking for a personal email address. If you present customer service, retail, or other experiences that request identification via email address, you can:" }, { "type": "list", "items": [ "Make sure that people can view their private relay address in your app or website", "Direct people to Settings > Apple Account > Password & Security > Apps using Apple Account to retrieve their private relay address", "Use other identifying values, like an order number or phone number collected as part of a purchase" ] }, { "type": "paragraph", "text": "Give people a chance to engage with your app before asking for optional data. As people use your app, you can help them discover places where they can benefit from sharing more information with you. For example, you might suggest that they provide a contact phone number if they want real-time text updates, or social network information if they want to play games with friends. If people choose not to provide optional information, don’t prevent them from accessing their account or using all the features of your app." }, { "type": "paragraph", "text": "Be transparent about the data you collect. People value knowing how you use the data that they share with you. One way you can be transparent is to welcome people by using the name or email address they shared. Doing this helps establish how you use this information and, for a relay address, shows people where to find it in the future. If you don’t display all the data that people provide, they are likely to wonder why you asked for it." } ] }, { "heading": "Displaying buttons", "level": 2, "content": [ { "type": "paragraph", "text": "Apple provides several Sign in with Apple buttons you can use to let people set up an account and sign in. If necessary, you can create a custom button to offer Sign in with Apple; for guidelines, see Creating a custom Sign in with Apple button." }, { "type": "paragraph", "text": "Prominently display a Sign in with Apple button. Make a Sign in with Apple button no smaller than other sign-in buttons, and avoid making people scroll to see the button." } ] }, { "heading": "Using the system-provided buttons", "level": 3, "content": [ { "type": "paragraph", "text": "When you use the system-provided APIs to create a Sign in with Apple button, you get the following advantages." }, { "type": "list", "items": [ "A button that’s guaranteed to use an Apple-approved appearance", "Assurance that the button’s contents maintain ideal proportions as you change its style", "Automatic translation of the button’s title into the language specified by the device", "Support for configuring the button’s corner radius to match the style of your UI (iOS, macOS, and web)", "A system-provided alternative text label that lets VoiceOver describe the button" ] }, { "type": "paragraph", "text": "For developer guidance, see ASAuthorizationAppleIDButton (iOS, macOS, and tvOS), WKInterfaceAuthorizationAppleIDButton (watchOS), and Displaying Sign in with Apple buttons on the web. You can also visit Sign in with Apple button to view and adjust live previews of web-based buttons and get the code." }, { "type": "paragraph", "text": "The system provides several variants of the button title. Depending on the platform on which your content runs, choose the variant that fits the terminology of your sign-in experience and use it consistently throughout your interfaces." }, { "type": "paragraph", "text": "The following button titles are available for iOS, macOS, tvOS, and the web:" }, { "type": "paragraph", "text": "For watchOS, the system provides one title:  Sign in." }, { "type": "paragraph", "text": "Depending on the platform, the system provides up to three options for the appearance of the Sign in with Apple button: white, white with an outline, and black. Choose the appearance that works best with the background on which the button displays." } ] }, { "heading": "White", "level": 4, "content": [ { "type": "paragraph", "text": "The white style is available on all platforms and the web. Use this style on dark backgrounds that provide sufficient contrast." } ] }, { "heading": "White with outline", "level": 4, "content": [ { "type": "paragraph", "text": "The white outlined style is available in iOS, macOS, and the web. Use this style on white or light-color backgrounds that don’t provide sufficient contrast with the white button fill. Avoid using this style on a dark or saturated background, because the black outline can add visual clutter; instead, use the white style to contrast with a dark background." } ] }, { "heading": "Black", "level": 4, "content": [ { "type": "paragraph", "text": "The black style is available on all platforms and the web. Use this style on white or light-color backgrounds that provide sufficient contrast; don’t use it on black or dark backgrounds." }, { "type": "paragraph", "text": "Unlike the black Sign in with Apple button for other platforms, the watchOS button uses a fill color that’s not fully black. To contrast with the pure black background of Apple Watch, the watchOS button uses the system-defined dark gray appearance." } ] }, { "heading": "Button size and corner radius", "level": 4, "content": [ { "type": "paragraph", "text": "Adjust the corner radius to match the appearance of other buttons in your app. By default, the Sign in with Apple button has rounded corners. In iOS, macOS, and the web, you can change the corner radius to produce a button with square corners or a capsule-shape button. For developer guidance, see cornerRadius (iOS and macOS) and Displaying Sign in with Apple buttons on the web." }, { "type": "paragraph", "text": "Minimum corner radius" }, { "type": "paragraph", "text": "Default corner radius" }, { "type": "paragraph", "text": "Maximum corner radius" }, { "type": "paragraph", "text": "Maintain the minimum button size and margin around the button in iOS, macOS, and the web. Be mindful that the button title may vary in length depending on the locale. Use the following values for guidance." }, { "type": "table", "rows": [ [ "Minimum width", "Minimum height", "Minimum margin" ], [ "140pt (140px @1x, 280px @2x)", "30pt (30px @1x, 60px @2x)", "1/10 of the button’s height" ] ] } ] }, { "heading": "Creating a custom Sign in with Apple button", "level": 3, "content": [ { "type": "paragraph", "text": "If your interface requires it, you can create a custom Sign in with Apple button for iOS, macOS, or the web. For example, you may want to align logos across multiple sign-in buttons, use buttons that display only a logo, or adjust the button’s font, bezel, or background appearance to coordinate with your UI." }, { "type": "paragraph", "text": "Always make sure that people can instantly identify your custom button as a Sign in with Apple button. If your custom button differs too much from the standard one, people may not feel comfortable using it to set up an account or sign in. App Review evaluates all custom Sign in with Apple buttons." }, { "type": "paragraph", "text": "Apple Design Resources provides downloadable Apple logo artwork you can use to create custom Sign in with Apple buttons that display either a logo only or a logo and text. The logo files are available in PNG, SVG, and PDF formats, and the artwork for both types of buttons includes both black and white versions. Here are examples of the black and white logo-only art files, each with a background added for visibility." }, { "type": "paragraph", "text": "All downloadable logo files include padding that simplifies positioning the logo in a button. Logo-only logo files include horizontal and vertical padding that ensures the correct proportion of the logo relative to the button. In addition to padding that keeps the logo and button correctly proportioned, logo files for buttons with text also include horizontal padding that provides a minimum margin between the logo and the button’s leading edge and title." }, { "type": "paragraph", "text": "Use only the logo artwork downloaded from Apple Design Resources; never create a custom Apple logo. As you create a custom Sign in with Apple button, follow these guidelines for using the downloadable logo file:" }, { "type": "list", "items": [ "Use the logo file to position the Apple logo in a button; never use the Apple logo as a button.", "Match the height of the logo file to the height of the button.", "Don’t crop the logo file.", "Don’t add vertical padding." ] }, { "type": "paragraph", "text": "To make sure that your custom button is visually consistent with the system-provided Sign in with Apple button, don’t change the following attributes." }, { "type": "list", "items": [ "Titles. Use only Sign in with Apple, Sign up with Apple, or Continue with Apple.", "General shape. Buttons that combine the logo with text are always rectangular; logo-only buttons can be circular or rectangular.", "Logo and title colors. Within a button, both items must be either black or white; don’t use custom colors." ] }, { "type": "paragraph", "text": "To coordinate with your app design, you can change:" }, { "type": "list", "items": [ "Title font. You can also adjust the font’s weight and size.", "Title case. You can capitalize every letter in the title.", "Background appearance. The overall color needs to remain black or white. If necessary, you can include a subtle texture or gradient to help the button harmonize with your interface.", "Button corner radius. You can use a corner radius value that matches the other buttons in your UI.", "Button bezel and shadow. For example, you can use a stroke to emphasize the button bezel or add a drop shadow." ] } ] }, { "heading": "Custom buttons with a logo and text", "level": 4, "content": [ { "type": "paragraph", "text": "Choose the format of the logo file based on the height of your button. Because SVG and PDF are vector-based formats, you can use these files in buttons of any height. Use the PNG files only in buttons that are 44 points tall, which is the default (and recommended) button height in iOS. Logos are available in small, medium, and large sizes, so you can match logo sizes in all the sign-up buttons you display." }, { "type": "paragraph", "text": "Prefer the system font for the title — that is, Sign in with Apple, Sign up with Apple, or Continue with Apple. Regardless of the font you choose, the title and button height of your custom button need to use the same proportions that the system uses. Using the system font for example, the title’s font size would be 43% of the button’s height — in other words, the button’s height would be 233% of the title’s font size, rounded to the nearest integer. Here are two examples that show these proportions using different sizes of the system font." }, { "type": "paragraph", "text": "In general, preserve the capitalization style of the title. By default, all variants of the button title capitalize the first word — that is, Sign or Continue — and Apple; all other letters are lowercase. Avoid changing this style unless your interface uses only uppercase." }, { "type": "paragraph", "text": "Keep the title and logo vertically aligned within the button. To do this, vertically align the title to the middle of the button, then add the logo image, making sure its height matches the height of the button. Because the logo image includes top and bottom padding, vertically aligning the title in the button ensures that the title, the logo, and the button stay properly aligned." }, { "type": "paragraph", "text": "Inset the logo if necessary. If you need to horizontally align the Apple logo with other authentication logos, you can adjust the space between the logo and the button’s leading edge." }, { "type": "paragraph", "text": "Maintain a minimum margin between the title and the right edge of the button. Ensure the margin measures at least 8% of the button’s width." }, { "type": "paragraph", "text": "Maintain the minimum button size and margin around the button. Be mindful that the button title may vary in length depending on the locale. Use the following values for guidance." }, { "type": "table", "rows": [ [ "Minimum width", "Minimum height", "Minimum margin" ], [ "140 pt (140 px @1x, 280 px @2x)", "30 pt (30 px @1x, 60 px @2x)", "1/10 of the button’s height" ] ] } ] }, { "heading": "Custom logo-only buttons", "level": 4, "content": [ { "type": "paragraph", "text": "Choose the format of the logo file based on the size of your button. The downloadable artwork for logo-only buttons is available in SVG, PDF, and PNG formats. Use the vector-based SVG and PDF formats for buttons of any size; use the PNG format only in buttons that measure 44x44 pt." }, { "type": "paragraph", "text": "Don’t add horizontal padding to a logo-only image. A logo-only Sign in with Apple button always has a 1:1 aspect ratio, and the artwork already includes the correct padding on all sides." }, { "type": "paragraph", "text": "Use a mask to change the default square shape of the logo-only image. For example, you might want to use a circular or rounded rectangular shape to present all logo-only sign-in buttons. Never crop the Apple-provided artwork to decrease its built-in padding or use the logo by itself, and avoid including additional padding." }, { "type": "paragraph", "text": "Rounded rectangle mask" }, { "type": "paragraph", "text": "No mask" }, { "type": "paragraph", "text": "Circular mask" }, { "type": "paragraph", "text": "Maintain a minimum margin around the button. Ensure the margin measures at least 1/10 of the button’s height." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Sign in with Apple button" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Authentication Services" }, { "type": "paragraph", "text": "Displaying Sign in with Apple buttons on the web — Sign in with Apple" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "September 14, 2022", "Refined guidance on supporting existing accounts, helping people set up a new account, and indicating the current sign-in status. Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Offering Sign in with Apple", "url": "/design/human-interface-guidelines/sign-in-with-apple#Offering-Sign-in-with-Apple" }, { "title": "Collecting data", "url": "/design/human-interface-guidelines/sign-in-with-apple#Collecting-data" }, { "title": "Displaying buttons", "url": "/design/human-interface-guidelines/sign-in-with-apple#Displaying-buttons" }, { "title": "Creating a custom Sign in with Apple button", "url": "/design/human-interface-guidelines/sign-in-with-apple#Creating-a-custom-Sign-in-with-Apple-button" }, { "title": "Using the system-provided buttons", "url": "/design/human-interface-guidelines/sign-in-with-apple#Using-the-system-provided-buttons" }, { "title": "White", "url": "/design/human-interface-guidelines/sign-in-with-apple#White" }, { "title": "White with outline", "url": "/design/human-interface-guidelines/sign-in-with-apple#White-with-outline" }, { "title": "white", "url": "https://developer.apple.com/design/human-interface-guidelines/sign-in-with-apple#White" }, { "title": "Black", "url": "/design/human-interface-guidelines/sign-in-with-apple#Black" }, { "title": "Button size and corner radius", "url": "/design/human-interface-guidelines/sign-in-with-apple#Button-size-and-corner-radius" }, { "title": "Custom buttons with a logo and text", "url": "/design/human-interface-guidelines/sign-in-with-apple#Custom-buttons-with-a-logo-and-text" }, { "title": "Custom logo-only buttons", "url": "/design/human-interface-guidelines/sign-in-with-apple#Custom-logo-only-buttons" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/sign-in-with-apple#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/sign-in-with-apple#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/sign-in-with-apple#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/sign-in-with-apple#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/sign-in-with-apple#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/sign-in-with-apple#Change-log" } ], "image_count": 0 }, { "title": "Siri", "url": "https://developer.apple.com/design/human-interface-guidelines/siri", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "When you use SiriKit to define the tasks and actions that your app supports, people can use Siri to perform them even when your app isn’t running. If you’re an accessory maker, you can also help people use Siri to control your accessories by integrating them with HomeKit or AirPlay. Here are some of the ways people can use Siri to interact with your app or accessory:" }, { "type": "list", "items": [ "Ask Siri to perform a system-defined task that your app supports, like send a message, play a song, or start a workout.", "Run a shortcut, which is a way to accelerate actions your app defines through onscreen interactions or by voice.", "Use the Shortcuts app to adjust what a shortcut does, including combining several actions to perform one multistep shortcut.", "Tap a suggestion to perform a shortcut with your app (Siri can suggest shortcuts that people might want to perform, based on their current context and the information you provide).", "Use Siri to control an accessory that integrates with your app." ] }, { "type": "paragraph", "text": "Siri works with your products on iPhone, iPad, Mac, Apple Watch, HomePod, and AirPods, so people can use it almost everywhere." }, { "type": "paragraph", "text": "When you make your app’s tasks available through Siri, you have several opportunities to customize the user experience. At a fundamental level, you customize the flow and functionality of the everyday tasks and actions you support to implement your business requirements. To reinforce this functionality throughout the user experience, you can write dialogue that reflects the style and tone of your company’s communications and design custom UI that incorporates your app’s visual style into the Siri interface." }, { "type": "paragraph", "text": "As you approach the job of integrating your app with Siri, assess the actions your app performs and learn how people use your app without voice interaction. Then consider the following steps:" }, { "type": "list", "items": [ "Identify key tasks in your app that people might want to perform on a regular basis.", "Drive engagement by telling the system about your app’s key tasks and by supporting suggestions.", "For actions that people can perform through voice interaction, design functional conversational flows that feel natural.", "Explore the various ways people might perform your app’s tasks — such as in a hands-free situation — and the devices they might be using, such as Apple Watch or iPad." ] } ] }, { "heading": "Integrating your app with Siri", "level": 2, "content": [ { "type": "paragraph", "text": "Tasks are at the core of your app’s integration with Siri. SiriKit builds on the idea of a person’s intention to perform a task by using the term intent to represent a task an app supports. The communication between your app and Siri is based on the intents — that is, the tasks — your app helps people perform." }, { "type": "paragraph", "text": "SiriKit defines system intents that represent common tasks — such as sending a message, calling a friend, and starting a workout — and groups related intents into domains. A domain is a category of tasks that Siri knows how to talk about, like messaging, calling, and workouts. For a complete list of domains and the actions in each domain that iOS and watchOS support, see System intents." }, { "type": "paragraph", "text": "When possible, take advantage of the intents that SiriKit defines. Using system-provided intents can make your job easier, while still giving you opportunities to customize the experience. However, if your app offers tasks that aren’t represented by system-defined intents — like ordering a meal or shopping for groceries — you can create a custom intent (for guidance, see Custom intents)." } ] }, { "heading": "A closer look at intents", "level": 3, "content": [ { "type": "paragraph", "text": "When people use Siri to ask questions and perform actions, Siri does the language processing and semantic analysis needed to turn their requests into intents for your app to handle. The exception is the personal phrase that people create to run a shortcut: When people speak the exact phrase, Siri recognizes it without doing additional processing or analysis." }, { "type": "paragraph", "text": "As a designer, your main job is to present clear, actionable content that helps clarify and streamline the interactions people have with Siri to get things done in your app. Some of these interactions happen while your app and SiriKit communicate about handling the intent, so it’s helpful to be familiar with the related SiriKit terminology. At a high level, your app processes an intent in three phases: resolve, confirm, and handle." }, { "type": "paragraph", "text": "First, your app and SiriKit must agree on what the request means in the resolve phase. You can think of this phase as the time to ask people for everything your app needs and, if necessary, ask for additional information or clarification. For example, if people ask to send a message to Amy, and they have multiple contacts named Amy, a messaging app can have Siri ask which Amy they mean. Details related to an intent, like a message recipient’s name, are known as parameters. In the resolve phase, you can indicate the parameters that are required to complete an action and those that are optional. For developer guidance, see Resolving the Parameters of an Intent." }, { "type": "paragraph", "text": "The second phase — called the confirm phase — happens when you have all the information you need to handle the intent. This phase can give people a chance to make sure they want to complete the task. For example, tasks that have financial impact require confirmation. In addition to asking for a person’s consent, you can present an error during this phase if something will prevent your app from completing the action. For example, if people use an app to order an item for pickup when the pickup location is closed, the app can describe why it can’t complete the action right now. Presenting this error during the confirm phase avoids making people wait until they’re paying for the item to find out that their request has failed. For developer guidance, see Confirming the Details of an Intent." }, { "type": "paragraph", "text": "Third, your app performs the task and tells SiriKit what it actually did in the handle phase. You can provide both visual and textual information that tells people what your app did to handle their request. For example, an app that lets people order coffee might present a receipt that describes the order. Siri can speak or display the information your app provides. For developer guidance, see Handling an Intent." } ] }, { "heading": "Provide information about actions and support suggestions", "level": 3, "content": [ { "type": "paragraph", "text": "Most apps support large numbers of actions, but people tend to perform only a handful of them on a regular basis. When you tell the system about people’s regular actions and describe new ones you think they’ll want to perform in the future, Siri can suggest shortcuts for both types of actions when people are likely to be interested in them." }, { "type": "paragraph", "text": "For example, in an app that’s all about coffee, the most frequent action might be to order a cup of coffee, while less frequent actions might include buying coffee beans or locating a new coffee shop. In this example, the coffee app would share information about the order coffee action so that Siri can suggest a shortcut for this action when people usually want to do it, like weekday mornings. The app could also tell Siri about an action that people haven’t performed yet, but might be interested in — like ordering a new seasonal variation of their favorite coffee — so that Siri might suggest a shortcut for this action." }, { "type": "paragraph", "text": "Siri can use signals like location, time of day, and type of motion (such as walking, running, or driving), to intelligently predict just the right time and place to suggest actions from your app. Depending on the information your app shares and people’s current context, Siri can offer shortcut suggestions on the lock screen, in search results, or on the Siri watch face. Siri can also use some types of information to suggest actions that system apps support, such as using Calendar to add an event shared by your app. Here are some example scenarios." }, { "type": "list", "items": [ "Shortly before 7:30 a.m., Siri might suggest the order coffee action to people who use the coffee app every morning.", "After people use a box office–type app to buy tickets to a movie, Siri might remind them to turn on Do Not Disturb shortly before showtime.", "Siri might suggest an automation that starts a workout in a person’s favorite workout app and plays their favorite workout playlist as they enter their usual gym.", "When people enter the airport after a home-bound flight, Siri might suggest they request a ride home from their favorite ride-sharing app." ] }, { "type": "paragraph", "text": "When you provide information about your actions to the system, people can also use the Shortcuts app to create shortcuts for the system and custom intents you support. For guidance, see Shortcuts and suggestions." } ] }, { "heading": "Design a great voice experience", "level": 3, "content": [ { "type": "paragraph", "text": "A great voice interface helps people feel confident they’ll get the results they want, even when they’re not sure what they can say. Siri supports different voice experiences for system-provided intents and custom intents. With a system intent, Siri does the natural language processing for you, letting people interact with your app in various conversational ways. With a custom intent, your app helps people perform a task that Siri doesn’t know about yet, which results in a different type of support for the voice experience. Custom intents give you additional opportunities to customize conversational dialogue, but also require people to create and speak a precise phrase to start the interaction." }, { "type": "paragraph", "text": "As a designer, you have several ways to enhance both types of conversational experiences and help people specify what they want without engaging in lengthy exchanges." }, { "type": "paragraph", "text": "For system-provided intents, you help Siri communicate with people about the action they want to accomplish by providing essential information and defining any app-specific terminology that might come up during the conversation. You don’t have to write additional dialogue for Siri to speak because Siri already knows about the actions in the system-defined domains and understands many ways that people may talk about them. For example, if you need to confirm the recipient’s name during the resolve phase of a messaging intent, you simply indicate that the required parameter value is missing and Siri says to the sender “Who do you want to send it to?”" }, { "type": "paragraph", "text": "Even though you don’t write custom dialogue for system-provided intents, you can enhance the voice experience in other ways. For example, if people ask Siri to “play MyMusicApp” as they enter their gym, you could respond by playing their workout playlist." }, { "type": "paragraph", "text": "When you support a custom intent, people start the action by using their personal invocation phrase; if people don’t speak their phrase precisely, Siri doesn’t initiate the intent. Although you can suggest a memorable phrase for people to use, your principal job is to write clear, direct dialogue, often in the form of follow-up questions, to help people accomplish the action in as few steps as possible." }, { "type": "paragraph", "text": "For example, a coffee app might suggest Order coffee as a phrase people could use to reorder a favorite cup of coffee. In a scenario where people usually use Order coffee to order a cappuccino in various sizes, the coffee app could follow up with custom dialogue that builds on this knowledge, like “What size of cappuccino?” For other types of actions, more open-ended questions can be better at helping people accomplish the task efficiently. For example, if people start a grocery shopping action by saying Add to cart, the grocery shopping app could follow up with “OK, what do you want?”" } ] }, { "heading": "Recognize that people use Siri in different contexts", "level": 3, "content": [ { "type": "paragraph", "text": "People can use Siri to get things done while they’re in a car, working out, using apps on a device, or interacting with HomePod. You don’t always know the context in which people are using Siri to perform your app’s actions, so flexibility is key to help people have a great experience no matter what they’re doing." }, { "type": "paragraph", "text": "To communicate with people regardless of their current context, supply information that Siri can provide both vocally and visually. Supporting both voice and screen-based content lets Siri decide which communication method works best for people in their current situation. For example, Siri speaks to people through their AirPods if they say “Hey Siri” while using them." }, { "type": "paragraph", "text": "In voice-only situations, Siri verbally describes information that would have been presented onscreen in other situations. Consider a food-delivery app that requires people to confirm a transaction before completing the order. In a voice-only scenario, Siri may say “Your total is fifteen dollars, and your order will take thirty minutes to arrive at your door. Ready to order?” In contrast, when people can view the cost and delivery information onscreen, Siri might simply say “Ready to order?” When you support custom intents, you’re responsible for supplying the voice-only dialogue that describes these types of onscreen information." } ] }, { "heading": "System intents", "level": 2, "content": [ { "type": "paragraph", "text": "SiriKit defines a large number of system intents that represent common tasks people do, such as playing music, sending messages to friends, and managing notes. For system intents, Siri defines the conversational flow, while your app provides the data to complete the interaction." }, { "type": "paragraph", "text": "SiriKit provides the following intents." }, { "type": "table", "rows": [ [ "Domain (link to developer guidance)", "Intents" ], [ "VoIP Calling", "Initiate calls." ], [ "Workouts", "Start, pause, resume, end, and cancel workouts." ], [ "Lists and Notes", "Create notes." ], [ "Search for notes." ], [ "Create reminders based on a date, time, or location." ], [ "Media", "Search for and play media content, such as video, music, audiobooks, and podcasts." ], [ "Like or dislike items." ], [ "Add items to a library or playlist." ], [ "Messaging", "Send messages." ], [ "Search for messages." ], [ "Read received messages." ], [ "Payments", "Send payments." ], [ "Request payments." ], [ "Car Commands", "Activate hazard lights or honk the horn." ], [ "Lock and unlock the doors." ], [ "Check the current fuel or power level." ] ] } ] }, { "heading": "Design responses to system intents", "level": 3, "content": [ { "type": "paragraph", "text": "People use Siri for convenience, and they expect a fast response. Your app needs to perform the system intents it supports quickly and accurately so that people have a great experience when they choose your app to get things done." }, { "type": "paragraph", "text": "Whenever possible, complete requests without leaving Siri. If a request must be finished in your app, take people directly to the expected destination. Don’t show intermediary screens or messages that slow down the experience." }, { "type": "paragraph", "text": "When a request has a financial impact, default to the safest and least expensive option. Never deceive people or misrepresent information. For a purchase with multiple pricing levels, don’t default to the most expensive. When people make a payment, don’t charge extra fees without informing them." }, { "type": "paragraph", "text": "When people request media playback from your app, consider providing alternative results if the request is ambiguous. When you display alternative results within the Siri UI, people can easily choose a different piece of content if your first offering isn’t what they want." }, { "type": "paragraph", "text": "On Apple Watch, design a streamlined workflow that requires minimal interaction. Whenever possible, use intelligent defaults instead of asking for input. For example, a music app could respond to a nonspecific request — like “Play music with MyMusicApp” — by playing a favorite playlist. If you must present options to people, offer a small number of relevant choices that reduce the need for additional prompting." } ] }, { "heading": "Enhance the voice experience for system intents", "level": 3, "content": [ { "type": "paragraph", "text": "Help people learn how to use Siri to get things done in your app, and make conversation with Siri feel natural in the context of your brand, by defining app-specific terms and alternative ways people might refer to your app." }, { "type": "paragraph", "text": "Create example requests. When people tap the Help button in the Siri interface, they view a guide that can include example phrases that you supply. Write phrases that demonstrate the easiest and most efficient ways to use Siri with your app. For developer guidance, see Intent Phrases." }, { "type": "paragraph", "text": "Define custom vocabulary that people use with your app. Help Siri learn more about the actions your app performs by defining specific terms people might actually use in requests, like account names, contact names, photo tags, photo album names, ride options, and workout names. Make sure these terms are nongeneric and unique to your app. Never include other app names, terms that are obviously connected with other apps, inappropriate language, or reserved phrases, like Hey Siri. Note that Siri uses the terms you define to help resolve requests, but there’s no guarantee that Siri will recognize them." }, { "type": "paragraph", "text": "Consider defining alternative app names. If people might refer to your app in different ways, it’s a good idea to provide a list of alternative names to help Siri understand what people mean. For example, a UnicornChat app might define the term Unicorn as an alternative app name. Never impersonate other apps by listing their names as alternative names for your app." } ] }, { "heading": "Design a custom interface for a system intent", "level": 3, "content": [ { "type": "paragraph", "text": "If it makes sense in your iOS app, you can supply custom interface elements or a completely custom UI for Siri or Maps to display along with your intent response. A watchOS app can’t provide a custom UI for Siri to display on Apple Watch." }, { "type": "paragraph", "text": "Avoid including extraneous or redundant information. A custom interface lets you bring elements from your app into the Siri interface, but displaying information that isn’t related to the action can distract people. You also want to avoid duplicating information that the system can display in the Siri or Maps interface. For developer guidance, see INParameter." }, { "type": "paragraph", "text": "Make sure people can still perform the action without viewing your custom interface. People can switch to voice-only interaction with Siri at any time, so it’s crucial to help Siri speak the same information that you display in your custom interface." }, { "type": "paragraph", "text": "Use ample margins and padding in your custom interface. Avoid extending content to the edges of your interface unless it’s content that appears to flow naturally offscreen, like a map. In general, provide a margin of 20 points between each edge of your interface and the content. Use the app icon that appears above your interface to guide alignment: content tends to look best when it’s lined up with the center of this icon." }, { "type": "paragraph", "text": "Minimize the height of your interface. The system displays other elements above and below your custom interface, such as the text prompt, the spoken response, and the Siri waveform. Aim for a custom interface height that’s no taller than half the height of the screen, so people can see all your content without scrolling." }, { "type": "paragraph", "text": "Refrain from displaying your app name or icon. The system automatically shows this information, so it’s redundant to include it in your custom interface." }, { "type": "paragraph", "text": "For developer guidance, see Creating an Intents UI Extension." } ] }, { "heading": "Custom intents", "level": 2, "content": [ { "type": "paragraph", "text": "If your app lets people perform an everyday task that doesn’t fit into any of the SiriKit domains, you can create a custom intent to represent it (see System intents for a list of domains). You can also use a custom or system intent to support a shortcut, which gives people a quick way to initiate frequently performed actions by speaking a simple phrase or accepting a suggestion from Siri. To learn how to integrate your intents with the system so that people can discover them and add them to Siri, see Shortcuts and suggestions." } ] }, { "heading": "Custom intent categories and responses", "level": 3, "content": [ { "type": "paragraph", "text": "Although your custom intent won’t belong to a SiriKit domain, you’ll need to model it on a system-defined intent category that’s related to your action. SiriKit defines several categories that represent generic tasks, like create, order, share, and search. Because these definitions are in the system, Siri knows how to communicate with people about common actions that are associated with each category — like placing an order or sharing content — in ways that feel natural." }, { "type": "paragraph", "text": "It’s important to choose the category that best represents your action because the category influences the ways Siri speaks about it and the controls people might see in the interface. For example, a coffee app would likely choose the order category to represent its custom order coffee intent, and as a result, Siri can speak default responses that make sense in the context of this action, like “Ready to order?” and “OK. Ordering.” Category choice can have other effects, too: Because the order category includes actions that have financial impact, using this category for the order coffee intent means that people will be asked to authenticate before completing the action." }, { "type": "paragraph", "text": "For several categories, the system defines additional verbs that are related to the category’s default action. You can use these alternative verbs to help ensure that the Siri dialogue and the button titles displayed in the interface align with the way you present your app’s actions. For example, in addition to the default verb order, the order category includes the verbs buy and book." }, { "type": "paragraph", "text": "SiriKit defines the following custom intent categories and associated verbs." }, { "type": "table", "rows": [ [ "Category", "Default verb", "Additional verbs" ], [ "Generic", "Do", "Run, go" ], [ "Information", "View", "Open" ], [ "Order", "Order", "Book, buy" ], [ "Start", "Start", "Navigate" ], [ "Share", "Share", "Post, send" ], [ "Create", "Create", "Add" ], [ "Search", "Search", "Find, filter" ], [ "Download", "Download", "Get" ], [ "Other", "Set", "Request, toggle, check in" ] ] }, { "type": "paragraph", "text": "SiriKit also defines three response types:" }, { "type": "list", "items": [ "Confirmation. Confirms that people still want to perform the action.", "Success. Indicates that the action has been initiated.", "Error. Tells people that the action can’t be completed." ] }, { "type": "paragraph", "text": "In several custom intent categories, SiriKit defines default dialogue for each response type. For example, the default confirmation dialogue for the order category is, “Ready to order?” and the default success dialogue for the share category is, “OK. Shared.”" }, { "type": "paragraph", "text": "To customize a response, you create a template that combines dialogue you write with placeholders for relevant information your app can supply while it’s working on the intent. For example, a coffee app might enhance the default order confirmation dialogue by providing custom content that includes a placeholder for the total cost of the order." }, { "type": "paragraph", "text": "Depending on the response type, your custom dialogue is presented before or after the default dialogue. For example, confirmation responses present the default dialogue after any custom dialogue. In the coffee app example, the customized confirmation dialogue would begin with something like, “Your large coffee with cream comes to $2.50” and end with the default dialogue, “Ready to order?”" } ] }, { "heading": "Design a custom intent", "level": 3, "content": [ { "type": "paragraph", "text": "If a built-in SiriKit intent represents your action’s purpose, adopt that intent instead of defining a custom intent. For example, if you’d like to offer a shortcut for sending a message, adopt INSendMessageIntent; if you’d like to offer a shortcut for playing media, adopt INPlayMediaIntent. For guidance, see System intents." }, { "type": "paragraph", "text": "If your app’s action requires a custom intent, pick the category that most closely matches the action. A category informs the system about the general function of an intent or shortcut — like order, download, or search — and affects the text and spoken dialogue presented to people when a shortcut is offered by the system or used with Siri. You design the flow of conversation for the custom intents you offer, so it’s essential that you choose a category that corresponds to the meaning of each intent." }, { "type": "tip", "text": "TipIf your action’s primary purpose is to retrieve information or show something to people — like displaying a sports score or the weather — use the information category. Using a different category requires people to make additional taps to get the information." }, { "type": "paragraph", "text": "Design custom intents that accelerate common, useful tasks. Take advantage of the familiarity people have with your app, and make it easier for them to initiate the tasks they perform most often." }, { "type": "paragraph", "text": "Ensure that your intent works well in every scenario. Make it easy for people to run your intent as a shortcut, regardless of how they initiate it. For example, be prepared for people to run it using their voice on devices with and without a screen, from suggestions on the lock screen or the Siri face on Apple Watch, from search, and within a multistep shortcut." }, { "type": "paragraph", "text": "In general, design custom intents for tasks that aren’t overly complex. People benefit the most from intents that reduce the number of actions required to complete a task. Don’t counteract that simplicity by requiring people to engage in a lengthy conversation with your app. You can also reduce the likelihood of user errors by limiting custom intents to clearly defined tasks." }, { "type": "paragraph", "text": "Design your intents to be long-lived. Avoid offering intents that are date-specific or associated with temporary data. For example, it’s not a good idea for a travel app to offer a custom intent for each specific itinerary. A better intent might use follow-up questions to let people get the itinerary for one of their upcoming trips." }, { "type": "paragraph", "text": "Don’t request permission to use Siri. If your app supports only custom intents — and not system intents — you don’t need to get permission to use Siri before letting people create and use voice shortcuts for your intents. Asking for permission can slow people down and could discourage them from using your app’s custom intents." }, { "type": "paragraph", "text": "Support background operation. The best intents support shortcuts that run quickly and don’t pull people out of their current context. Strive to support custom intents that can run in the background without bringing your app to the front. Supporting background operation also ensures that people can complete the task in hands-free and voice-only scenarios." } ] }, { "heading": "Help people customize their requests", "level": 3, "content": [ { "type": "paragraph", "text": "Custom intents can offer follow-up questions that let people do more with a single intent by refining its results on the fly. For example, if you offer an order coffee intent, you can help people get exactly what they want by asking them questions like, “What size?”, “What flavor?”, and “Which location?” Details like size, flavor, and location are parameters your app can define to help people personalize their request." }, { "type": "paragraph", "text": "People supply parameter values to personalize an intent by responding to your follow-up questions or by editing existing values in the Shortcuts app. For example, if you offer an order ground coffee intent that includes a parameter for the grind size, you might supply a follow-up question like, “Which grind?” For people who typically order the coarse grind, you could simplify the interaction by using the value coarse as the default parameter value in a dialogue like, “Do you want coarse-ground coffee?” If people choose a different grind, you can follow up by presenting the full list of options. In voice-only scenarios, Siri speaks your follow-up questions and sends you the responses. When people use the Shortcuts app to edit a parameter value, you receive the new value when they use the associated shortcut. For developer guidance, see Adding User Interactivity with Siri Shortcuts and the Shortcuts App." }, { "type": "paragraph", "text": "Design intents that require as few follow-up questions as possible. Often, an intent can fulfill a request without asking any follow-up questions. Although follow-up questions make intents more flexible, you don’t want to force people into a long interaction. In most cases, it’s best to offer just one or two follow-up questions." }, { "type": "paragraph", "text": "List the smallest number of options possible, and sort the items in a way that makes sense. As with too many follow-up questions, giving people too many options can make completing the task feel onerous. As you determine whether to include an item, consider its complexity as well as its utility. In a food-ordering app, for example, it might be easier for people to parse a list of individual menu items than a list of orders, each of which contains multiple items. After you identify a small number of useful items, consider sorting them by recency, frequency, or popularity." }, { "type": "paragraph", "text": "Make sure each follow-up question is meaningful. Ideally, each follow-up question helps people make an important choice. If options or questions you present are too granular or too similar, the conversation can become repetitive, and people may feel like using your intent is too much work." }, { "type": "paragraph", "text": "Design parameters that are easy for people to understand and use. Aim for parameters that represent simple values or attributes and name them using simple, straightforward terms. For example, a soup-ordering app might define parameters for the type of soup, the serving size, and a delivery location, using names like soup, size, and location. For guidance, see Shortcuts and suggestions." }, { "type": "paragraph", "text": "Ask for confirmation only when necessary. An intent can ask people for confirmation before completing the task or when interpreting an answer to a follow-up question. Apps that support tasks that have financial impact, like an app that helps people place orders, must ask for confirmation before completing an order. For tasks that don’t have financial impact, asking for confirmation can feel like too much extra work and can sometimes discourage people from completing their request. In all cases, avoid asking for confirmation more than once." }, { "type": "paragraph", "text": "Support follow-up questions when it makes sense. For example, an app that helps people order food might offer options for pickup or delivery, but ask for a specific location only after people choose the delivery option." }, { "type": "paragraph", "text": "Prioritize the options you offer based on the context in which people run your shortcut. For example, if people use your shortcut to order an item for pickup, offer pickup locations that are currently close by. Offering options that adapt to the context in which your shortcut is run can help people avoid creating separate shortcuts for specific options." }, { "type": "paragraph", "text": "Consider adjusting the parameter values you offer when people set up your shortcut. When you indicate that a parameter has dynamic options, you can enhance the shortcut setup experience in two ways:" }, { "type": "list", "items": [ "You can find and present parameter values that are relevant to the context people are in while they’re setting up the shortcut. For example, if people use the Shortcuts app to choose a value for a store-location parameter, the parameter can dynamically generate a list of stores that are currently closest to the device.", "You can present a comprehensive list of parameter values. When people set up a shortcut, having an extensive list of parameter values can help them create the shortcut they want. In contrast, when people use a shortcut to accelerate an action, they generally prefer the convenience of having a shorter list of choices." ] }, { "type": "paragraph", "text": "For developer guidance, see the storeLocation parameter in the intent definition file of the Soup Chef: Accelerating App Interactions with Shortcuts sample code project." } ] }, { "heading": "Enhance the voice experience for custom intents", "level": 3, "content": [ { "type": "paragraph", "text": "Aim to create conversational interactions. You can customize what Siri says throughout the voice experience, including the handling of follow-up questions. Try writing a script and acting it out with another person to see how well your dialogue works in a face-to-face exchange. Experiencing custom dialogue in this way can help you find places where the interaction doesn’t feel natural." }, { "type": "paragraph", "text": "Help people understand errors and failures. The system provides some default error descriptions, but it’s best to enhance error responses so that they’re specific to the current situation. For example, if chicken noodle soup is sold out, a soup app can respond with a custom error like, “Sorry, we’re out of chicken noodle soup” instead of “Sorry, we can’t complete your order.”" }, { "type": "paragraph", "text": "Strive for engaging voice responses. Remember that people may perform your app’s tasks from their HomePod, using “Hey Siri” with their AirPods, or through CarPlay without looking at a screen. In these cases, the voice response needs to convey the same essential information that the visual elements display to ensure that people can get what they need no matter how they interact with Siri." }, { "type": "paragraph", "text": "Create voice responses that are concise, descriptive, and effective in voice-driven scenarios. As with a shortcut title, an effective custom spoken response clearly conveys what’s happening as the shortcut runs. If you ask follow-up questions, be sure to customize the default dialogue for clarity. For example, “Which soup?” is clearer than “Which one?”" }, { "type": "paragraph", "text": "Avoid unnecessary repetition. People tend to run voice shortcuts frequently, so they may hear the same prompt multiple times when answering follow-up questions or dealing with errors. Use the context of the current conversation to remove as many details from the prompts as possible. Avoid including unnecessary words or attempts at humor, because both can become irritating over time." }, { "type": "paragraph", "text": "Help conversations with Siri feel natural. People interact with Siri in a variety of ways, like choosing a list item by saying “the second one,” or, in the case of a soup-ordering app, saying “large” or “small” instead of “bowl” or “cup.” You can make people’s Siri interactions feel more natural when you give the system alternative terms and phrases that work as app-specific synonyms (like using “bowl” as a synonym for “large”). Also consider enhancing clarity by providing alternative dialogue options for Siri to speak. For example, the soup app might present a list of onscreen menu options like “1 clam chowder,” or “1 clam chowder and 1 tomato,” but speak these options as “Which order? The one with clam chowder only or the one that includes tomato?”" }, { "type": "paragraph", "text": "Exclude your app name. The system provides verbal and visual attribution for your app when responding to people. Including your appʼs name in a verbal response is redundant and may make the experience of interacting with Siri feel less natural. Siri speaks your app’s name less frequently when people have used a shortcut several times, because it isn’t necessary to keep reminding them which app is responding." }, { "type": "paragraph", "text": "Don’t attempt to mimic or manipulate Siri. Never impersonate Siri, attempt to reproduce the functionality that Siri provides, or provide a response that appears to come from Apple." }, { "type": "paragraph", "text": "Be appropriate and respect parental controls. Never present offensive or demeaning content. Keep in mind that many families use parental controls to restrict explicit content and content that’s based on specific rating levels." }, { "type": "paragraph", "text": "Avoid using personal pronouns. Create content that’s inclusive of all people." }, { "type": "paragraph", "text": "Consider letting people view more options in your app. If the list of options doesn’t include the items people need, you might want to include an item that lets people open your app to see more. In the list, you could use copy like, “See more in App Name,” and in spoken dialogue, you might encourage people to say, “More options.”" }, { "type": "paragraph", "text": "Keep responses device-independent. People may use Siri to interact with your app via Apple Watch, HomePod, iPad, iPhone, or CarPlay. If you must provide device-specific wording, make sure it accurately reflects the person’s current device." }, { "type": "paragraph", "text": "Don’t advertise. Don’t include advertisements, marketing, or in-app purchase sales pitches in your intent content." } ] }, { "heading": "Shortcuts and suggestions", "level": 2, "content": [ { "type": "paragraph", "text": "When you support shortcuts, people have a variety of ways to discover and interact with the custom and system intents your app provides. For example:" }, { "type": "list", "items": [ "Siri can suggest a shortcut for an action people have performed at least once by offering it in search results, on the lock screen, and in the Shortcuts app.", "Your app can supply a shortcut for an action that people haven’t done yet but might want to do in the future, so that the Shortcuts app can suggest it or it can appear on the Siri watch face.", "People can use the Shortcuts app to view all their shortcuts and even combine actions from different apps into multistep shortcuts.", "People can also use the Shortcuts app to automate a shortcut by defining the conditions that can run it, like time of day or current location." ] }, { "type": "paragraph", "text": "The Shortcuts app is also available in macOS 12 and later and in watchOS 7 and later. For developer guidance, see SiriKit." }, { "type": "note", "text": "Developer noteThe Add to Siri method for adding shortcuts is no longer supported. See App Shortcuts for ways to integrate your app with Siri and the system." } ] }, { "heading": "Make app actions widely available", "level": 3, "content": [ { "type": "paragraph", "text": "Donating information about the actions your app supports helps the system offer them to people in various ways, such as:" }, { "type": "list", "items": [ "In search results", "Throughout the Shortcuts app", "On the lock screen as a Siri Suggestion", "Within the Now Playing view (for recently played media content)", "During Wind Down" ] }, { "type": "paragraph", "text": "Donations also power Automation Suggestions in the Shortcut app’s Gallery, making it easy for people to set up automations for hands-free interactions with your app." }, { "type": "paragraph", "text": "You can also tell the system about shortcuts for actions people haven’t taken yet or make a shortcut available on the Siri watch face (for guidance, see Suggest Shortcuts people might want to add to Siri and Display shortcuts on the Siri watch face). For developer guidance, see Donating Shortcuts." }, { "type": "paragraph", "text": "Make a donation every time people perform the action. When you donate a shortcut each time people perform the associated action, you help the system more accurately predict the best time and place to offer the shortcut." }, { "type": "paragraph", "text": "Only donate actions that people actually perform. For example, a coffee-ordering app donates the Order coffee shortcut every time people order coffee, but not when people do something else, like browse the menu. Similarly, a media app donates information about a song — like its title and album — only when people are actually listening to it. (For developer guidance, see Improving Siri Media Interactions and App Selection.)" }, { "type": "paragraph", "text": "Remove donations for actions that require corresponding data. If information required by a donated action no longer exists, your app needs to delete the donation so the shortcut isn’t suggested anymore. For example, if people delete a contact in a messaging app, the app needs to delete donations for messaging that contact. When people create a shortcut themselves, only they can delete it. For developer guidance, see Deleting Donated Shortcuts." }, { "type": "paragraph", "text": "If your app handles reservations, consider donating them to the system. These items — like ticketed events, travel itineraries, or reservations for restaurants, flights, or movies — automatically appear as suggestions in Calendar or Maps. When you donate a reservation, it can appear on the lock screen with a suggestion to check in with your app or as a reminder that uses current traffic conditions to recommend when people should leave. For developer guidance, see Donating Reservations." } ] }, { "heading": "Suggest Shortcuts people might want to add to Siri", "level": 4, "content": [ { "type": "paragraph", "text": "If your app supports an action that people haven’t performed yet but might find useful, you can provide a suggested shortcut to the system so that people can discover it. For example, if people use a coffee-ordering app to order their daily coffee but not to order a holiday special, the app might still want to give them a way to do this with an Order holiday coffee shortcut." }, { "type": "paragraph", "text": "Suggested shortcuts appear in both the Gallery and the shortcut editor in the Shortcuts app. For developer guidance, see Offering Actions in the Shortcuts App." } ] }, { "heading": "Display shortcuts on the Siri watch face", "level": 4, "content": [ { "type": "paragraph", "text": "On Apple Watch, people can run shortcuts in several ways. For example, people can ask Siri, tap a shortcut complication on a watch face, or use the Shortcuts app available in watchOS 7 and later. You can also make shortcuts available on the Siri watch face." }, { "type": "paragraph", "text": "To have a shortcut appear on the Siri watch face, you define a relevant shortcut by including information like the time of day at which your shortcut is relevant and how the shortcut can display on the Siri watch face. The information you supply lets the Siri watch face intelligently display your shortcut to people when they’re in the appropriate context." }, { "type": "paragraph", "text": "For developer guidance, see Defining Relevant Shortcuts for the Siri Watch Face." } ] }, { "heading": "Create shortcut titles and subtitles", "level": 3, "content": [ { "type": "paragraph", "text": "Shortcut titles and subtitles appear when the system suggests them. In Siri Suggestions on iPhone and Apple Watch, a shortcut can also display an image." }, { "type": "paragraph", "text": "Be concise but descriptive. An effective title conveys what happens when the shortcut runs. A subtitle can provide additional detail that supplements — but doesn’t duplicate — the title." }, { "type": "paragraph", "text": "Start titles with a verb and use sentence-style capitalization without punctuation. Think of a shortcut title as a brief instruction." }, { "type": "table", "rows": [ [ "", "Example title" ], [ "", "Order my favorite coffee" ], [ "", "Large latte" ], [ "", "Show today’s forecast" ], [ "", "Weather forecast" ] ] }, { "type": "paragraph", "text": "Lead with important information. Long titles and subtitles may be truncated in certain contexts, depending on the device’s screen size." }, { "type": "paragraph", "text": "Exclude your app name. The system already identifies the app associated with a shortcut." }, { "type": "paragraph", "text": "Localize titles and subtitles. Providing content in multiple languages ensures an equally great experience for people everywhere." }, { "type": "paragraph", "text": "Consider providing a custom image for a more engaging suggestion. For example, the shortcut for Order my favorite coffee could show a cup of the customer’s favorite coffee. Create an image that measures:" }, { "type": "list", "items": [ "60x60 pt (180x180 px @ 3x) to display in an iOS app", "34x34 pt (68x68 px @2x) to display on the Siri watch face on the 44mm Apple Watch (watchOS scales down the image for smaller watches)" ] } ] }, { "heading": "Provide default phrases for shortcuts", "level": 3, "content": [ { "type": "paragraph", "text": "Your app provides default phrases for shortcuts during setup. People can personalize these phrases when adding your shortcuts to Siri." }, { "type": "paragraph", "text": "Keep phrases short and memorable. Bear in mind that people must speak your phrase verbatim, so long or confusing phrases may result in mistakes and frustration. Two- and three-word phrases tend to work best. More words can be harder for people to remember, and phrases that are too long will get truncated." }, { "type": "paragraph", "text": "Make sure the phrases you suggest are accurate and specific. Phrases like Reorder coffee or Order my usual coffee clearly describe what the shortcut does, which makes it easier for people to remember the phrase later. Also make sure that your suggested phrases are specific to each shortcut’s scope. For example, Watch baseball is clearer and more memorable than Watch sports. It’s also important to avoid implying that people can vary a shortcut’s invocation phrase to get a different result. For example, people might interpret a phrase like Order a large clam chowder to mean that your shortcut will give them what they want if they substitute “small” for “large” and “lobster bisque” for “clam chowder.”" }, { "type": "paragraph", "text": "Don’t commandeer core Siri commands. For example, never suggest a phrase like Call 911 or include the text Hey Siri." } ] }, { "heading": "Make shortcuts customizable", "level": 3, "content": [ { "type": "paragraph", "text": "When you define a parameter for each detail your app needs to perform an intent, people can customize the shortcut by editing these details in the Shortcuts app." }, { "type": "paragraph", "text": "To show people which details they can edit and how their edits affect the action, you provide a parameter summary. A parameter summary succinctly describes the action by using the parameters in a sentence that begins with a verb. For example, a customizable Order coffee shortcut could display a parameter summary like “Order quantity coffee” where quantity and coffee are the parameters that people can edit. Here’s an example of how the Order coffee shortcut might look after people supply values for the quantity and coffee parameters." }, { "type": "paragraph", "text": "Provide a parameter summary for each custom intent you support. At minimum, include in your parameter summary all parameters your intent requires and any parameters that receive values from other apps or actions. The summary doesn’t have to include optional parameters or parameters that people aren’t likely to edit; if you omit parameters like these from the summary, people can still access them in the Show More section." }, { "type": "paragraph", "text": "Craft a short parameter summary that’s clearly related to your intent’s title. When the intent title and the parameter summary are similar, it’s easy for people to recognize the action regardless of where they view it. Aim to use the same words in the summary and the title — in particular, it’s helpful to begin both phrases with the same verb. For example, if your intent title is “Search encyclopedia,” a good parameter summary could be “Search encyclopedia for search term.”" }, { "type": "paragraph", "text": "Aim for a parameter summary that reads like a sentence. Use sentence-style capitalization, but don’t include ending punctuation. When possible, avoid punctuation entirely. Punctuation within a summary — especially colons, semicolons, and parentheses — can make the summary hard to read and understand." }, { "type": "paragraph", "text": "Provide multiple parameter summaries when necessary. If your action includes a parameter that has a parent-child relationship with other parameters, you can provide multiple variants of the summary based on the current value of the parent parameter. For example, if your order coffee shortcut lets people specify whether they want to pick up their order or have it delivered, your parameter summary can reflect the current choice. In this scenario, create one parameter summary that helps people pick a store location and another summary that helps them pick a delivery address. Be sure to use a consistent grammatical structure and parameter order in all variants of the summary that you create." }, { "type": "paragraph", "text": "Provide output parameters for information that people can use in a multistep shortcut. For example, an order coffee action might provide output that includes the estimated delivery time and the cost of the order. With this information, people could create a multistep shortcut that messages a friend about the delivery time and logs the transaction in their favorite budgeting app." }, { "type": "paragraph", "text": "Consider defining an input parameter. When you define an input parameter for an action, the action can automatically receive output from a preceding action in a multistep shortcut. For example, if your action applies a filter to the image it receives in an image parameter, you might designate image as the input parameter so that it automatically accepts images from other actions. You configure an input parameter in your intent definition file (shown in Adding User Interactivity with Siri Shortcuts and the Shortcuts App)." }, { "type": "paragraph", "text": "Help people distinguish among different variations of the same action. For example, an app that offers a send message action might use a contact photo to help people visually distinguish the various messages they send. To do this, choose the parameter that’s most identifiable to people and designate it as the key parameter (shown in Adding User Interactivity with Siri Shortcuts and the Shortcuts App). Be sure to provide an image for the key parameter every time you donate the action (for developer guidance, see INImage)." }, { "type": "paragraph", "text": "Avoid providing multiple actions that perform the same basic task. For example, instead of providing an action that adds text to a note and a different action that adds an image, consider providing a single action that lets people add both types of content. Providing a few high-level actions can make it easier for people to understand what the actions do when they’re combined in a multistep shortcut." }, { "type": "paragraph", "text": "For developer guidance, see Shortcut-Related UI." } ] }, { "heading": "Editorial guidelines", "level": 2, "content": [ { "type": "paragraph", "text": "Don’t refer to Siri using pronouns like “she,” “him,” or “her.” Ideally, just use the word Siri. For example, After you add a shortcut to Siri, you can run the shortcut anytime by asking Siri." }, { "type": "paragraph", "text": "Use correct capitalization and punctuation when using the term Hey Siri. Hey Siri is two words, italicized or in quotes, with an uppercase H and uppercase S. Do not follow the term with an ellipsis." }, { "type": "table", "rows": [ [ "", "Example text" ], [ "", "Say Hey Siri to activate Siri." ], [ "", "Say “Hey Siri” to activate Siri." ], [ "", "Say Hey Siri… to activate Siri." ], [ "", "Say “hey Siri” to activate Siri." ] ] }, { "type": "paragraph", "text": "In a localized context, translate only the word Hey in the phrase Hey Siri. As an Apple trademark, Siri is never translated. Here is a list of acceptable translations for the phrase Hey Siri:" }, { "type": "table", "rows": [ [ "Locale code", "Hey Siri translation", "Locale code", "Hey Siri translation" ], [ "ar_AE", "يا Siri", "fr_CA", "Dis Siri" ], [ "ar_SA", "يا Siri", "fr_CH", "Dis Siri" ], [ "da_DK", "Hej Siri", "fr_FR", "Dis Siri" ], [ "de_AT", "Hey Siri", "it_CH", "Ehi Siri" ], [ "de_CH", "Hey Siri", "it_IT", "Ehi Siri" ], [ "de_DE", "Hey Siri", "ja_JP", "Hey Siri" ], [ "en_AU", "Hey Siri", "ko_KR", "Siri야" ], [ "en_CA", "Hey Siri", "ms_MY", "Hai Siri" ], [ "en_GB", "Hey Siri", "nb_NO", "Hei Siri" ], [ "en_IE", "Hey Siri", "nl_BE", "Hé, Siri" ], [ "en_IN", "Hey Siri", "nl_NL", "Hé Siri" ], [ "en_NZ", "Hey Siri", "no_NO", "Hei Siri" ], [ "en_SG", "Hey Siri", "pt_BR", "E aí Siri" ], [ "en_US", "Hey Siri", "ru_RU", "привет Siri" ], [ "en_ZA", "Hey Siri", "sv_SE", "Hej Siri" ], [ "es_CL", "Oye Siri", "th_TH", "หวัดดี Siri" ], [ "es_ES", "Oye Siri", "tr_TR", "Hey Siri" ], [ "es_MX", "Oye Siri", "zh_CN", "嘿Siri" ], [ "es_US", "Oye Siri", "zh_HK", "喂 Siri" ], [ "fi_FI", "Hei Siri", "zh_TW", "嘿 Siri" ], [ "fr_BE", "Dis Siri", "", "" ] ] } ] }, { "heading": "Referring to Shortcuts", "level": 3, "content": [ { "type": "paragraph", "text": "When referring to the Shortcuts feature or app, always typeset with a capital S and make sure that Shortcuts is plural. For example, MyApp integrates with Shortcuts to provide a quick way to get things with just a tap or by asking Siri." }, { "type": "paragraph", "text": "When referring to individual shortcuts (that is, not the feature or the Shortcuts app), use lowercase. For example, Run a shortcut by asking Siri or tapping a suggestion on the Lock Screen." }, { "type": "paragraph", "text": "Use the right terminology when describing how people can use Shortcuts in your app. People run shortcuts by asking Siri, so your wording needs to be very similar to phrases like Run a shortcut by asking Siri or Run the shortcut by asking Siri with your personalized phrase (localized as appropriate). Avoid using phrases like add voice shortcuts, make a voice command, create a voice prompt, or any other variation. Instead, consider a phrase like Add a shortcut to Siri to run with your voice (localized as appropriate)." }, { "type": "paragraph", "text": "To encourage people to create or use shortcuts in ways other than voice — like automations, Home Screen shortcuts, and other methods — use a phrase that doesn’t specify a particular method, like For quick access, add to Shortcuts." }, { "type": "note", "text": "NoteUse translations of your app name and the word Shortcuts — but not Siri — when referring to them in a localized context." } ] }, { "heading": "Referring to Apple products", "level": 3, "content": [ { "type": "paragraph", "text": "Adhere to Apple’s trademark guidelines. Apple trademarks can’t appear in your app name or images. In text, use Apple product names exactly as shown on the Apple Trademark List." }, { "type": "list", "items": [ "Use Apple product names in singular form only; don’t make Apple product names possessive.", "Don’t translate Apple, Siri, or any other Apple trademark.", "Don’t use category descriptors. For example, say iPad, not tablet.", "Don’t indicate any kind of sponsorship, partnership, or endorsement from Apple.", "Attribute Apple, Siri, and all other Apple trademarks with the correct credit lines wherever legal information appears within your app.", "Refer to Apple devices and operating systems only in technical specifications or compatibility descriptions." ] }, { "type": "paragraph", "text": "See Guidelines for Using Apple Trademarks." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "App Shortcuts" }, { "type": "paragraph", "text": "Design for intelligence" }, { "type": "paragraph", "text": "Guidelines for using Apple trademarks and copyrights" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "SiriKit" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 5, 2023", "Removed Add to Siri guidance. Added references to the new App Shortcuts page." ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "HomeKit", "url": "/design/human-interface-guidelines/homekit" }, { "title": "AirPlay", "url": "/design/human-interface-guidelines/airplay" }, { "title": "Integrating your app with Siri", "url": "/design/human-interface-guidelines/siri#Integrating-your-app-with-Siri" }, { "title": "System intents", "url": "/design/human-interface-guidelines/siri#System-intents" }, { "title": "Custom intents", "url": "/design/human-interface-guidelines/siri#Custom-intents" }, { "title": "A closer look at intents", "url": "/design/human-interface-guidelines/siri#A-closer-look-at-intents" }, { "title": "Provide information about actions and support suggestions", "url": "/design/human-interface-guidelines/siri#Provide-information-about-actions-and-support-suggestions" }, { "title": "Shortcuts and suggestions", "url": "/design/human-interface-guidelines/siri#Shortcuts-and-suggestions" }, { "title": "Design a great voice experience", "url": "/design/human-interface-guidelines/siri#Design-a-great-voice-experience" }, { "title": "Recognize that people use Siri in different contexts", "url": "/design/human-interface-guidelines/siri#Recognize-that-people-use-Siri-in-different-contexts" }, { "title": "Design responses to system intents", "url": "/design/human-interface-guidelines/siri#Design-responses-to-system-intents" }, { "title": "Enhance the voice experience for system intents", "url": "/design/human-interface-guidelines/siri#Enhance-the-voice-experience-for-system-intents" }, { "title": "Design a custom interface for a system intent", "url": "/design/human-interface-guidelines/siri#Design-a-custom-interface-for-a-system-intent" }, { "title": "Custom intent categories and responses", "url": "/design/human-interface-guidelines/siri#Custom-intent-categories-and-responses" }, { "title": "Design a custom intent", "url": "/design/human-interface-guidelines/siri#Design-a-custom-intent" }, { "title": "Help people customize their requests", "url": "/design/human-interface-guidelines/siri#Help-people-customize-their-requests" }, { "title": "Enhance the voice experience for custom intents", "url": "/design/human-interface-guidelines/siri#Enhance-the-voice-experience-for-custom-intents" }, { "title": "App Shortcuts", "url": "/design/human-interface-guidelines/app-shortcuts" }, { "title": "Make app actions widely available", "url": "/design/human-interface-guidelines/siri#Make-app-actions-widely-available" }, { "title": "Suggest Shortcuts people might want to add to Siri", "url": "/design/human-interface-guidelines/siri#Suggest-Shortcuts-people-might-want-to-add-to-Siri" }, { "title": "Display shortcuts on the Siri watch face", "url": "/design/human-interface-guidelines/siri#Display-shortcuts-on-the-Siri-watch-face" }, { "title": "complication", "url": "/design/human-interface-guidelines/complications" }, { "title": "Create shortcut titles and subtitles", "url": "/design/human-interface-guidelines/siri#Create-shortcut-titles-and-subtitles" }, { "title": "Provide default phrases for shortcuts", "url": "/design/human-interface-guidelines/siri#Provide-default-phrases-for-shortcuts" }, { "title": "Make shortcuts customizable", "url": "/design/human-interface-guidelines/siri#Make-shortcuts-customizable" }, { "title": "Editorial guidelines", "url": "/design/human-interface-guidelines/siri#Editorial-guidelines" }, { "title": "Referring to Shortcuts", "url": "/design/human-interface-guidelines/siri#Referring-to-Shortcuts" }, { "title": "Referring to Apple products", "url": "/design/human-interface-guidelines/siri#Referring-to-Apple-products" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/siri#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/siri#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/siri#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/siri#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/siri#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/siri#Change-log" } ], "image_count": 0 }, { "title": "Tap to Pay on iPhone", "url": "https://developer.apple.com/design/human-interface-guidelines/tap-to-pay-on-iphone", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "When you support Tap to Pay on iPhone in your iOS payment app, you help merchants present a consistent and trusted payment experience to their customers." }, { "type": "note", "text": "NoteTap to Pay on iPhone works alongside your existing payment-acceptance hardware and accessories." }, { "type": "paragraph", "text": "Before you can integrate Tap to Pay on iPhone into your iOS app, you need to work with a supported payment service provider (PSP), request the Tap to Pay on iPhone entitlement, and use ProximityReader APIs, either through the PSP’s SDK or by adopting the framework. For high-level guidance — including marketing recommendations for letting people know about your app’s new capabilities — see Tap to Pay on iPhone; for developer guidance, see Setting up Tap to Pay on iPhone." }, { "type": "note", "text": "NoteIf your PSP offers an SDK that supplies user interfaces for experiences like showing a tap result, see the documentation the PSP provides." } ] }, { "heading": "Enabling Tap to Pay on iPhone", "level": 2, "content": [ { "type": "paragraph", "text": "Before your app can enable Tap to Pay on iPhone and configure a merchant’s device, the merchant must accept the relevant terms and conditions. Use the ProximityReader API to help you get the current status and present an acceptance flow only when necessary. For developer guidance, see Adding support for Tap to Pay on iPhone to your app." }, { "type": "paragraph", "text": "Help merchants accept Tap to Pay on iPhone terms and conditions before they begin interacting with their customers. Merchants must accept the terms and conditions before you perform the initial device configuration, so it works well when they can do so before they begin a checkout or other customer-facing flow. For example, you can provide buttons that let people accept Tap to Pay on iPhone terms and conditions from within your in-app messaging or onboarding flows." }, { "type": "paragraph", "text": "An app screen that offers a way to accept Tap to Pay on iPhone terms and conditions" }, { "type": "paragraph", "text": "An app screen that shows Tap to Pay on iPhone is enabled and offers a way to try it" }, { "type": "paragraph", "text": "Present Tap to Pay on iPhone terms and conditions only to an administrative user. If a nonadministrator tries to activate the feature, present a message explaining that administrator access is required. If your app’s primary users are enterprise or nonadministrative users, you can let an administrator accept Tap to Pay on iPhone terms and conditions through a web interface or a different app, including one that can run on devices other than iPhone. Contact your PSP for implementation details." }, { "type": "paragraph", "text": "If necessary, help merchants make sure their device is up to date. If your PSP requires specific versions of iOS, be sure to present the terms and conditions only after the merchant updates their device." } ] }, { "heading": "Educating merchants", "level": 2, "content": [ { "type": "paragraph", "text": "Some merchants may be unfamiliar with Tap to Pay on iPhone, so it’s important to give them a quick and easy way to get started." }, { "type": "paragraph", "text": "Provide a tutorial that describes the supported payment types and shows how to use Tap to Pay on iPhone to accept each type. You can offer this tutorial by:" }, { "type": "list", "items": [ "Including it in a Learn More option in your in-app messaging", "Automatically presenting it after merchants accept the Tap to Pay on iPhone terms and conditions", "Automatically presenting it to new users of your app", "Making it easy to find in a consistent place like your app’s help content or settings area" ] }, { "type": "paragraph", "text": "You can build your app’s tutorial using Apple-approved assets from the Tap to Pay on iPhone marketing guidelines, or you can use the ProximityReaderDiscovery API to provide a pre-built merchant education experience. Apple ensures that the API is up to date and is localized for the merchant’s region." }, { "type": "paragraph", "text": "Your app’s settings area is a good place to make sure the tutorial is always available." }, { "type": "paragraph", "text": "The merchant education tutorial provided by the ProximityReaderDiscovery API." }, { "type": "paragraph", "text": "If you design your own tutorial, make sure it shows how to:" }, { "type": "list", "items": [ "Launch a checkout flow for each type of payment", "Help a customer position their contactless card or digital wallet on the merchant’s device for payment", "Handle PIN entry for a card, including accessibility mode" ] }, { "type": "paragraph", "text": "Finally, provide an opportunity at the end of the tutorial for merchants who haven’t accepted the Tap to Pay on iPhone terms and conditions yet to do so." } ] }, { "heading": "Checking out", "level": 2, "content": [ { "type": "paragraph", "text": "Checking out is a time-sensitive action, and merchants need the process to work smoothly. As you design your checkout flow, be prepared to:" }, { "type": "list", "items": [ "Offer payment options in addition to Tap to Pay on iPhone, as necessary", "Respond quickly if a merchant initiates checkout before enabling Tap to Pay on iPhone", "Help merchants perform checkout even if device configuration is still in progress", "Present pre-payment actions that affect the final total before checkout completes" ] }, { "type": "paragraph", "text": "Provide Tap to Pay on iPhone as a checkout option whether the feature is enabled or not. Including a Tap to Pay on iPhone button gives merchants the flexibility to use the feature without exiting the checkout flow. When merchants tap the button, present the terms and conditions if necessary and automatically display the Tap to Pay on iPhone screen when configuration completes." }, { "type": "paragraph", "text": "Avoid making merchants wait to use Tap to Pay on iPhone. In addition to performing the initial configuration for each device, you need to perform a subsequent configuration each time your app becomes frontmost. To minimize potential wait times, prepare the feature as soon as your app starts and immediately after each transition to the foreground. For developer guidance, see prepare(using:)." }, { "type": "paragraph", "text": "Make sure the Tap to Pay on iPhone checkout option is available even if configuration is continuing in the background. Merchants must always be able to select the Tap to Pay on iPhone checkout option in a checkout flow. During configuration, let merchants select the checkout option and then display a progress indicator — avoid waiting for configuration to complete before making the option available. In most scenarios, you can display an indeterminate progress indicator, but if ProximityReader API shows that configuration is ongoing, display a determinate progress indicator. For guidance, see Progress indicators; for developer guidance see PaymentCardReader.Event.updateProgress(_:)." }, { "type": "paragraph", "text": "An app screen that displays a determinate progress indicator during configuration" }, { "type": "paragraph", "text": "An app screen that displays an indeterminate progress indicator during configuration" }, { "type": "paragraph", "text": "If your app supports multiple payment-acceptance methods, make the Tap to Pay on iPhone button easy to find. Avoid making merchants scroll to access the feature. If your app doesn’t support other payment acceptance options, open Tap to Pay on iPhone automatically when checkout begins." }, { "type": "paragraph", "text": "Make it easy for merchants to switch between Tap to Pay on iPhone and the hardware accessories you support. Even though your support for Tap to Pay on iPhone is separate from your support for a hardware accessory, such as a Bluetooth chip and PIN card reader, you can streamline the user experience by helping merchants set up both methods at the same time. After setup, make sure merchants can choose the appropriate payment-acceptance method during the checkout flow without having to visit your app settings." }, { "type": "paragraph", "text": "For the label of the button that activates the feature, use “Tap to Pay on iPhone” or, if space is constrained, “Tap to Pay.” The exception is if Tap to Pay on iPhone is the only payment-acceptance method you support. In this case, you can reuse your existing Charge or Checkout buttons to activate Tap to Pay on iPhone. If you support multiple payment-acceptance methods and you use icons in the buttons that activate them, use the wave.3.right.circle or wave.3.right.circle.fill SF Symbols in your Tap to Pay on iPhone button. Always avoid including the Apple logo in Tap to Pay on iPhone buttons." }, { "type": "important", "text": "ImportantUse the “Tap to Pay on iPhone” label only for payment actions. For language you can use for nonpayment actions, see Additional interactions." }, { "type": "paragraph", "text": "Design your Tap to Pay on iPhone button to match the other buttons in your app. Although you must use the labels “Tap to Pay on iPhone” or “Tap to Pay” as described above, you can use the button color and shape that coordinate best with your interface." }, { "type": "paragraph", "text": "Determine the final amount that customers need to pay before merchants initiate the Tap to Pay on iPhone experience. For example, if your app supports tipping or other customer interactions that can affect the total, make sure merchants offer these interactions before displaying the Tap to Pay on iPhone screen. Aim to display the final amount customers need to pay in the Tap to Pay on iPhone screen." }, { "type": "paragraph", "text": "If you support pre-payment options in your checkout flow, display them before the Tap to Pay on iPhone screen. For example, if you support the selection of different payment types, you can display these options in your checkout screen after a merchant taps the Tap to Pay on iPhone button and before you open the Tap to Pay on iPhone screen." } ] }, { "heading": "Displaying results", "level": 2, "content": [ { "type": "paragraph", "text": "Customers pay by tapping — that is, bringing a contactless card or digital wallet near the Tap to Pay on iPhone screen in your app. After a successful tap (and after a successful PIN entry, if required), Tap to Pay on iPhone displays a checkmark and gives your app an object that contains the encrypted payment information you send to your PSP for processing. When a tap fails, Tap to Pay on iPhone displays an error screen. Your app is responsible for displaying transaction results after a successful tap or offering alternative payment options after an unsuccessful tap." }, { "type": "paragraph", "text": "Start processing a transaction as soon as possible. The system provides API you can use to request the result of a successful tap before the Tap to Pay on iPhone screen finishes displaying the checkmark animation that indicates tap completion. For developer guidance, see returnReadResultImmediately." }, { "type": "paragraph", "text": "Display a progress indicator while payment is authorizing before you show your transaction result screen. Transaction authorization can take several seconds to complete, depending on factors like connectivity for both the PSP and the merchant’s device. To ensure a smooth visual transition, display your authorization progress indicator after the Tap to Pay on iPhone screen animation finishes (for developer guidance, see PaymentCardReader.Event.readyForTap)." }, { "type": "paragraph", "text": "Clearly display the result of a transaction, whether it’s declined or successful. A transaction can be declined for reasons like insufficient funds, suspicion of fraud, or when the customer enters an incorrect PIN. As much as possible, also give the merchant ways to offer customers a digital receipt, such as through a QR code or text message." }, { "type": "paragraph", "text": "Help merchants complete the checkout flow when a payment can’t complete with Tap to Pay on iPhone. For example, a tap can fail when a card isn’t readable, isn’t from a supported payment network, doesn’t allow transactions at the stated amount, or doesn’t allow online PIN entry. In cases like these, you can:" }, { "type": "list", "items": [ "Present a new screen or reuse your checkout screen, letting merchants accept an alternate form of payment, like cash", "Support checkout with a different method, like external hardware or a payment link", "Relaunch Tap to Pay on iPhone, if a customer has another card they want to try" ] }, { "type": "paragraph", "text": "After you receive payment card data, you might also encounter scenarios like the ones listed below. If such scenarios occur, contact your PSP for guidance on addressing them." }, { "type": "list", "items": [ "Some regions require Strong Customer Authentication (SCA) support, which means that although the payment card might not require a card PIN during a tap, the bank that issues the card can request a PIN after receiving the transaction processing request. In this scenario, your app may need to display the PIN entry screen instead of the transaction result.", "In some regions your app may need to meet additional requirements to address the limitations of some cards, such as those in Offline PIN markets. Some PSPs support additional PIN fallback functionality to collect partial data from a tap, letting merchants continue the payment with another method such as a payment link." ] }, { "type": "paragraph", "text": "If the system returns an error that the merchant must address, display a clear description of the problem and recommend an appropriate resolution. For example, if the device’s version of iOS doesn’t support Tap to Pay on iPhone, present an alert that recommends updating to the latest version. For developer guidance, see PaymentCardReaderSession.ReadError." }, { "type": "paragraph", "text": "Make it easy for merchants to get help with issues they can’t resolve. For example, direct merchants to the help content in your app or on your website, and provide an action that contacts your support team." } ] }, { "heading": "Additional interactions", "level": 2, "content": [ { "type": "paragraph", "text": "Tap to Pay on iPhone lets merchants read a payment card when there’s no transaction amount to support use cases like looking up a past transaction, or retaining card information to ensure future payment, issue refunds, or verify customer information." }, { "type": "paragraph", "text": "Use a generic label in a button that opens the Tap to Pay on iPhone screen to read a payment card when there’s no transaction amount. Don’t include “Tap to Pay on iPhone” or “Tap to Pay” in such a label; instead, use a generic label like “Look Up,” “Store Card,” “Verify,” or “Refund.”" }, { "type": "paragraph", "text": "When customers have other types of NFC-compatible cards or passes in Apple Wallet — such as loyalty, discount, and points cards — Tap to Pay on iPhone lets merchants read these items at the same time that they read a payment card or independently." }, { "type": "paragraph", "text": "If your app supports an independent loyalty card transaction, distinguish this flow from a payment-acceptance flow that uses Tap to Pay on iPhone. It works well to give merchants a separate, clearly labeled button to initiate a loyalty card transaction. To help merchants avoid choosing the wrong button by mistake, avoid including “Tap to Pay on iPhone,” “Tap to Pay,” or other payment-related terms in the label for a loyalty-transaction button." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS. Not supported in iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Tap to Pay on iPhone Marketing guidelines" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Adding support for Tap to Pay on iPhone to your app — ProximityReader" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "January 17, 2024", "Updated merchant education guidance." ], [ "May 7, 2024", "Updated to include guidance on enabling the feature and educating merchants." ], [ "March 3, 2023", "Enhanced guidance for educating merchants and improving their experience." ], [ "September 14, 2022", "Refined guidance on preparing Tap to Pay on iPhone and helping merchants learn how to use the feature." ] ] } ] } ], "platforms": [], "related": [ { "title": "Enabling Tap to Pay on iPhone", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Enabling-Tap-to-Pay-on-iPhone" }, { "title": "Educating merchants", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Educating-merchants" }, { "title": "Checking out", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Checking-out" }, { "title": "Progress indicators", "url": "/design/human-interface-guidelines/progress-indicators" }, { "title": "SF Symbols", "url": "/design/human-interface-guidelines/sf-symbols" }, { "title": "Additional interactions", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Additional-interactions" }, { "title": "Displaying results", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Displaying-results" }, { "title": "alert", "url": "/design/human-interface-guidelines/alerts" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone#Change-log" } ], "image_count": 0 }, { "title": "Technologies", "url": "https://developer.apple.com/design/human-interface-guidelines/technologies", "category": "technologies", "summary": "", "sections": [], "platforms": [], "related": [ { "title": "AirPlay", "url": "/design/human-interface-guidelines/airplay" }, { "title": "Always On", "url": "/design/human-interface-guidelines/always-on" }, { "title": "App Clips", "url": "/design/human-interface-guidelines/app-clips" }, { "title": "Apple Pay", "url": "/design/human-interface-guidelines/apple-pay" }, { "title": "Augmented reality", "url": "/design/human-interface-guidelines/augmented-reality" }, { "title": "CareKit", "url": "/design/human-interface-guidelines/carekit" }, { "title": "CarPlay", "url": "/design/human-interface-guidelines/carplay" }, { "title": "Game Center", "url": "/design/human-interface-guidelines/game-center" }, { "title": "Generative AI", "url": "/design/human-interface-guidelines/generative-ai" }, { "title": "HealthKit", "url": "/design/human-interface-guidelines/healthkit" }, { "title": "HomeKit", "url": "/design/human-interface-guidelines/homekit" }, { "title": "iCloud", "url": "/design/human-interface-guidelines/icloud" }, { "title": "ID Verifier", "url": "/design/human-interface-guidelines/id-verifier" }, { "title": "iMessage apps and stickers", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers" }, { "title": "In-app purchase", "url": "/design/human-interface-guidelines/in-app-purchase" }, { "title": "Live Photos", "url": "/design/human-interface-guidelines/live-photos" }, { "title": "Mac Catalyst", "url": "/design/human-interface-guidelines/mac-catalyst" }, { "title": "Machine learning", "url": "/design/human-interface-guidelines/machine-learning" }, { "title": "Maps", "url": "/design/human-interface-guidelines/maps" }, { "title": "NFC", "url": "/design/human-interface-guidelines/nfc" }, { "title": "Photo editing", "url": "/design/human-interface-guidelines/photo-editing" }, { "title": "ResearchKit", "url": "/design/human-interface-guidelines/researchkit" }, { "title": "SharePlay", "url": "/design/human-interface-guidelines/shareplay" }, { "title": "ShazamKit", "url": "/design/human-interface-guidelines/shazamkit" }, { "title": "Sign in with Apple", "url": "/design/human-interface-guidelines/sign-in-with-apple" }, { "title": "Siri", "url": "/design/human-interface-guidelines/siri" }, { "title": "Tap to Pay on iPhone", "url": "/design/human-interface-guidelines/tap-to-pay-on-iphone" }, { "title": "VoiceOver", "url": "/design/human-interface-guidelines/voiceover" }, { "title": "Wallet", "url": "/design/human-interface-guidelines/wallet" } ], "image_count": 0 }, { "title": "VoiceOver", "url": "https://developer.apple.com/design/human-interface-guidelines/voiceover", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "By supporting VoiceOver, you help people who are blind or have low vision access information in your app and navigate its interface and content when they can’t see the display." }, { "type": "paragraph", "text": "VoiceOver is supported in apps and games built for Apple platforms. It’s also supported in apps and games developed in Unity using Apple’s Unity plug-ins. For related guidance, see Accessibility." } ] }, { "heading": "Descriptions", "level": 2, "content": [ { "type": "paragraph", "text": "You inform VoiceOver about your app’s content by providing alternative text that explains your app’s interface and the content it displays." }, { "type": "paragraph", "text": "Provide alternative labels for all key interface elements. VoiceOver uses alternative labels (which aren’t visible onscreen) to audibly describe your app’s interface. System-provided controls have generic labels by default, but you should provide more descriptive labels that convey your app’s functionality. Add labels to any custom elements your app defines. Be sure to keep your descriptions up-to-date as your app’s interface and content change. For developer guidance, see Accessibility modifiers." }, { "type": "paragraph", "text": "Describe meaningful images. If you don’t describe key images in your app’s content, people can’t use VoiceOver to fully experience them within your app. Because VoiceOver helps people understand the interface surrounding images too, such as nearby captions, describe only the information the image itself conveys." }, { "type": "paragraph", "text": "Make charts and other infographics fully accessible. Provide a concise description of each infographic that explains what it conveys. If people can interact with the infographic to get more or different information, make these interactions available to people using VoiceOver, too. The accessibility APIs offer ways to represent custom interactive elements so that assistive technologies can help people use them. For guidance, see Charts." }, { "type": "paragraph", "text": "Exclude purely decorative images from VoiceOver. It’s unnecessary to describe images that are decorative and don’t convey useful or actionable information. Excluding these images shows respect for people’s time and reduces cognitive load when they use VoiceOver. For developer guidance, see accessibilityHidden(_:), accessibilityElement, and isAccessibilityElement." } ] }, { "heading": "Navigation", "level": 2, "content": [ { "type": "paragraph", "text": "Use titles and headings to help people navigate your information hierarchy. The title is the first information someone receives from an assistive technology when arriving on a page or screen in your app. Offer unique titles that succinctly describe each page’s content and purpose. Likewise, use accurate section headings that help people build a mental model of each page’s information hierarchy." }, { "type": "paragraph", "text": "Specify how elements are grouped, ordered, or linked. Proximity, alignment, and other visible contextual cues help sighted people perceive the relationships between elements. Examine your app for places where relationships among elements are visual only. Then, describe these relationships to VoiceOver." }, { "type": "paragraph", "text": "VoiceOver reads elements in the same order people read content in the their active language and locale. For example, in US English, this is top-to-bottom, left-to-right. In the ungrouped example below, VoiceOver describes each image before moving on to the captions. In the grouped example, VoiceOver describes each image with its respective caption." }, { "type": "paragraph", "text": "Ungrouped related elements make it hard for VoiceOver to accurately describe the UI." }, { "type": "paragraph", "text": "Grouped related elements help VoiceOver accurately describe the UI." }, { "type": "paragraph", "text": "For developer guidance, see shouldGroupAccessibilityChildren." }, { "type": "paragraph", "text": "Inform VoiceOver when visible content or layout changes occur. People may find an unexpected content or layout change confusing because it means their mental map of the content is no longer accurate. It’s crucial to report visible changes so VoiceOver and other assistive technologies can help people update their understanding of the content. For developer guidance, see AccessibilityNotification." }, { "type": "paragraph", "text": "Support the VoiceOver rotor when possible. People can use an interface element called the VoiceOver rotor to navigate a document or webpage by headings, links, and other content types. You can help people navigate content in your app by identifying these elements to the rotor. The rotor can also bring up the braille keyboard. For developer guidance, see AccessibilityRotorEntry (SwiftUI), UIAccessibilityCustomRotor (UIKit), and NSAccessibilityCustomRotor (AppKit)." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, or watchOS." } ] }, { "heading": "visionOS", "level": 3, "content": [ { "type": "paragraph", "text": "Be mindful that custom gestures aren’t always accessible. When VoiceOver is turned on in visionOS, apps and games that define custom gestures don’t receive hand input by default. This ensures people can explore the interface using their voice, without an app responding to hand input at the same time. A person can opt out of this behavior by enabling Direct Gesture mode, which disables standard VoiceOver gestures and lets apps process hand input directly. For developer guidance, see Improving accessibility support in your visionOS app." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Accessibility" }, { "type": "paragraph", "text": "Inclusion" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Accessibility" }, { "type": "paragraph", "text": "VoiceOver" }, { "type": "paragraph", "text": "Supporting VoiceOver in your app" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "March 7, 2025", "New page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Accessibility", "url": "/design/human-interface-guidelines/accessibility" }, { "title": "Descriptions", "url": "/design/human-interface-guidelines/voiceover#Descriptions" }, { "title": "Navigation", "url": "/design/human-interface-guidelines/voiceover#Navigation" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/voiceover#Platform-considerations" }, { "title": "visionOS", "url": "/design/human-interface-guidelines/voiceover#visionOS" }, { "title": "Resources", "url": "/design/human-interface-guidelines/voiceover#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/voiceover#Related" }, { "title": "Inclusion", "url": "/design/human-interface-guidelines/inclusion" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/voiceover#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/voiceover#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/voiceover#Change-log" } ], "image_count": 0 }, { "title": "Wallet", "url": "https://developer.apple.com/design/human-interface-guidelines/wallet", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "People use their cards and passes in Wallet to make Apple Pay purchases, track their orders, confirm their identity, and streamline activities like boarding a plane, attending a concert, or receiving a discount." }, { "type": "paragraph", "text": "When you integrate Apple Wallet into your app, you can create custom passes and present them the moment people need them, securely verify an individual’s identity so they can access personal content, and offer detailed receipts and tracking information where it’s most convenient. For developer guidance, see Wallet." } ] }, { "heading": "Passes", "level": 2, "content": [ { "type": "paragraph", "text": "Offer to add new passes to Wallet. When people do something that results in a new pass — like checking into a flight, purchasing an event ticket, or registering for a store reward program — you can present system-provided UI that helps them add the pass to Wallet with one tap (for developer guidance, see addPasses(_:withCompletionHandler:)). If people want to review a pass before adding it, you can display a custom view that displays the pass and provides an Add to Apple Wallet button; for developer guidance, see PKAddPassesViewController." }, { "type": "paragraph", "text": "Help people add a pass that they created outside of your app. If people create a pass using your website or another device, suggest adding it to Wallet the next time they open your app. If people decline your suggestion, don’t ask them again." }, { "type": "paragraph", "text": "Add related passes as a group. If your app generates multiple passes, like boarding passes for a multi-connection flight, add all passes at the same time so people don’t have to add each one individually. If people can receive a group of passes from your website — such as a set of tickets for an event — bundle them together so that people can download all of them at one time. For developer guidance, see Distributing and updating a pass." }, { "type": "paragraph", "text": "Display an Add to Apple Wallet button to let people add an existing pass that isn’t already in Wallet. If people previously declined your suggestion to add a pass to Wallet — or if they removed the pass — a button makes it easy to add it if they change their minds. You can display an Add to Apple Wallet button wherever the corresponding pass information appears in your app. For developer guidance, see PKAddPassButton. You can also display an Add to Apple Wallet badge in an email or on a webpage; for guidance, see Add to Apple Wallet guidelines." }, { "type": "paragraph", "text": "Let people jump from your app to their pass in Wallet. Wherever your app displays information about a pass that exists in Wallet, you can offer a link that opens it directly. Label the link something like “View in Wallet.”" }, { "type": "paragraph", "text": "Tell the system when your pass expires. Wallet automatically hides expired passes to reduce crowding, while also providing a button that lets people revisit them. To help ensure the system hides passes appropriately, set the expiration date, relevant date, and voided properties of each pass correctly; for developer guidance, see Pass." }, { "type": "paragraph", "text": "Always get people’s permission before deleting a pass from Wallet. For example, you could include an in-app setting that lets people specify whether they want to delete passes manually or have them removed automatically. If necessary, you can display an alert before deleting a pass." }, { "type": "paragraph", "text": "Help the system suggest a pass when it’s contextually relevant. Ideally, passes automatically appear when they’re needed so people don’t have to manually locate them. When you supply information about when and where your pass is relevant, the system can display a link to it on the Lock Screen when people are most likely to want it. For example, a gym membership card could appear on the Lock Screen as people enter the gym. For developer guidance, see Showing a Pass on the Lock Screen. Starting in iOS 18 and watchOS 11, the system starts a Live Activity for poster event ticket style passes when they’re relevant." }, { "type": "paragraph", "text": "Lock screen notification" }, { "type": "paragraph", "text": "Live Activity" }, { "type": "paragraph", "text": "Update passes as needed. Physical passes don’t typically change, but a digital pass can reflect updates to events. An airline boarding pass, for example, can automatically update to display flight delays and gate changes." }, { "type": "paragraph", "text": "Use change messages only for updates to time-critical information. A change message interrupts people’s current workflow, so it’s essential to send one only when you make an update they need to know about. For example, people need to know when there’s a gate change in a boarding pass, but they don’t need to know when a customer service phone number changes. Never use a change message for marketing or other noncritical communication. Change messages are available on a per-field basis; for developer guidance, see Adding a Web Service to Update Passes." } ] }, { "heading": "Designing passes", "level": 2, "content": [ { "type": "paragraph", "text": "Wallet uses a consistent design aesthetic to strengthen familiarity and build trust. Instead of merely replicating the appearance of a physical item, design a clean, simple pass that looks at home in Wallet." }, { "type": "paragraph", "text": "Design a pass that looks great and works well on all devices. Passes can look different on different devices. For example, when a pass appears on Apple Watch, it doesn’t display all the images it displays when it appears on iPhone (for guidance, see Passes for Apple Watch). Don’t put essential information in elements that might be unavailable on certain devices. Also, don’t add padding to images; for example, watchOS crops white space from some images." }, { "type": "paragraph", "text": "Avoid using device-specific language. You can’t predict the device people will use to view your pass, so don’t write text that might not make sense on a particular device. For example, text that tells people to “slide to view” content doesn’t make sense when it appears on Apple Watch." }, { "type": "paragraph", "text": "Make your pass instantly identifiable. Using color — especially a color that’s linked to your brand — can help people recognize your pass as soon as they see it. Make sure that pass content remains comfortably readable against the background you choose." }, { "type": "paragraph", "text": "Keep the front of a pass uncluttered so people can get important information at a glance. Show essential information — like an event date or account balance — in the top-right area of the pass so people can still see it when the pass is collapsed in Wallet. Use the rest of the pass front to provide important information; consider putting extra information on the back of a pass (iOS) or in a details screen (watchOS)." }, { "type": "paragraph", "text": "Prefer an NFC-compatible pass. People appreciate having a contactless pass, because it means that they can just hold their device near a reader. If you support both NFC and a barcode or QR code, the code appears on the back of the pass (in iOS) or in the details screen (in watchOS). In iOS, you can display a QR code or barcode on the front of your pass if necessary for your design." }, { "type": "paragraph", "text": "Reduce image sizes for optimal performance. People can receive passes via email or a webpage. To make downloads as fast as possible, use the smallest image files that still look great." }, { "type": "paragraph", "text": "Provide an icon that represents your company or brand. The system includes your icon when displaying information about a relevant pass on the Lock Screen. Mail also uses the icon to represent your pass in an email message. You can use your app icon or design an icon for this purpose." } ] }, { "heading": "Pass styles", "level": 3, "content": [ { "type": "paragraph", "text": "The system defines several pass styles for categories like boarding pass, coupon, store card, and event ticket. Pass styles specify the appearance and layout of content in your pass, and the information that the system needs to suggest your pass when it’s relevant (for guidance, see Passes)." }, { "type": "paragraph", "text": "Although each pass style is different, all styles display information using the basic layout areas shown below:" }, { "type": "paragraph", "text": "All passes display a logo image, and some can display additional images in other areas depending on the pass style. To display information in the layout areas, use the following PassFields." }, { "type": "table", "rows": [ [ "Field", "Layout area", "Use to provide…" ], [ "Header", "Essential", "Critical information that needs to remain visible when the pass is collapsed in Wallet." ], [ "Primary", "Primary", "Important information that helps people use the pass." ], [ "Secondary and auxiliary", "Secondary and auxiliary", "Useful information that people might not need every time they use the pass." ], [ "Back", "Not shown in diagram", "Supplemental details that don’t need to be on the pass front." ] ] }, { "type": "paragraph", "text": "In general, a pass can have up to three header fields, one primary field, up to four secondary fields, and up to four auxiliary fields. Depending on the amount of content you display in each field, some fields may not be visible." }, { "type": "paragraph", "text": "Display text only in pass fields. Don’t embed text in images — it’s not accessible and not all images are displayed on all devices — and avoid using custom fonts that might make text hard to read." } ] }, { "heading": "Boarding passes", "level": 4, "content": [ { "type": "paragraph", "text": "Use the boarding pass style for train tickets, airline boarding passes, and other types of transit passes. Typically, each pass corresponds to a single trip with a specific starting and ending point." }, { "type": "paragraph", "text": "A boarding pass can display logo and footer images, and it can have up to two primary fields and up to five auxiliary fields." } ] }, { "heading": "Coupons", "level": 4, "content": [ { "type": "paragraph", "text": "Use the coupon style for coupons, special offers, and other discounts. A coupon can display logo and strip images, and it can have up to four secondary and auxiliary fields, all displayed on one row." } ] }, { "heading": "Store cards", "level": 4, "content": [ { "type": "paragraph", "text": "Use the store card style for store loyalty cards, discount cards, points cards, and gift cards. If an account related to a store card carries a balance, the pass usually shows the current balance." }, { "type": "paragraph", "text": "A store card can display logo and strip images, and it can have up to four secondary and auxiliary fields, all displayed on one row." } ] }, { "heading": "Event tickets", "level": 4, "content": [ { "type": "paragraph", "text": "Use the event ticket pass style to give people entry into events like concerts, movies, plays, and sporting events. Typically, each pass corresponds to a specific event, but you can also use a single pass for several events, as with a season ticket." }, { "type": "paragraph", "text": "An event ticket can display logo, strip, background, or thumbnail images. However, if you supply a strip image, don’t include a background or thumbnail image. You can also include an extra row of up to four auxiliary fields. For developer guidance, see the row property of PassFields.AuxiliaryFields." }, { "type": "paragraph", "text": "In iOS 18 and later, the system defines an additional style for contactless event tickets called poster event ticket. Poster event tickets offer a rich visual experience that prominently features the event artwork, provides easy access to additional event information, and integrates with system apps like Weather and Maps." }, { "type": "important", "text": "ImportantPoster event tickets aren’t compatible with tickets that require a QR code or barcode for entry." }, { "type": "paragraph", "text": "A poster event ticket displays an event logo and background image, and can optionally display a separate ticket issuer or event company logo. The system uses metadata about your event to structure ticket information and suggest relevant actions. You must provide a required set of metadata in SemanticTags for all poster event tickets, and an additional set of required metadata depending on the event type — general, sports, or live performance. You can also add optional metadata to further enhance your ticket. For example, you can specify an admission level for a live performance, like General Admission, which the system displays with the seating information. For developer guidance, see Supporting semantic tags in Wallet passes." }, { "type": "paragraph", "text": "The system uses the metadata that you provide to generate a Maps shortcut to the venue directions and an event guide below the ticket when in the Wallet app. The event guide provides convenient access to information like the weather forecast and venue map, and to quick actions like checking the baggage policy and ordering food. You can display a minimum of one and up to four quick action buttons in the event guide; if you include more than four, the system collapses them into a menu. You can optionally include additional ticket information, such as pre-paid parking details, which the system also displays below the ticket." }, { "type": "paragraph", "text": "Additional ticket information, Maps shortcut, and event guide tiles below the ticket in the Wallet app" }, { "type": "paragraph", "text": "Event guide" }, { "type": "paragraph", "text": "Create a vibrant and engaging background. As the centerpiece of a poster event ticket, your background image serves as a visual representation of the event. Limit text in your artwork, and create an image that’s easily identifiable to help people quickly find their ticket among other passes in their Wallet app. If your background image is a solid color or includes a solid color in the footer, consider setting a footer background color to better blend the background image with the footer." }, { "type": "paragraph", "text": "Position your background image in the safe area. The system displays ticket information in the header and footer, which overlap the background image. To ensure that the content in your artwork isn’t covered, position it in the safe area. For developer guidance, see footerBackgroundColor in Pass." }, { "type": "paragraph", "text": "Ensure sufficient contrast so that ticket information is easy to read. By default, the system applies a gradient in the header and a blur effect in the footer of your poster event ticket to provide sufficient contrast between the background image and ticket information. Consider adjusting the gradient and blur effect if you need more contrast. The system can also automatically determine the best text color for ticket information and labels based on your background image. If you choose to customize text colors, make sure to select a color that provides sufficient contrast, especially if you set a footer background color or a seat section color to support wayfinding. For developer guidance, see useAutomaticColors in Pass and seatSectionColor in SemanticTagType.Seat." }, { "type": "paragraph", "text": "Consider using the additional information tile for extra event details. When you have more information about the event that people may find helpful, the additional information tile below the ticket is a great place to put it. If you have additional information that’s essential to display on the front of the ticket, keep the text short to avoid cluttering the footer. For developer guidance, see additionalTicketAttributes in SemanticTags and PassFields.AdditionalInfoFields." }, { "type": "paragraph", "text": "Continue to support event tickets for earlier versions of iOS. People expect contactless event tickets to work, regardless of their device’s software version. Continue to provide primary, secondary, and auxiliary information in PassFields and image assets for your event ticket. This enables the system to automatically generate the appropriate ticket style for a person’s device; otherwise, your ticket appears empty on devices running earlier versions of iOS." } ] }, { "heading": "Generic passes", "level": 4, "content": [ { "type": "paragraph", "text": "Use the generic style for a type of pass that doesn’t fit into the other categories, such as a gym membership card or coat-check claim ticket. A generic pass can display logo and thumbnail images, and it can have up to four secondary and auxiliary fields, all displayed on one row." } ] }, { "heading": "Passes for Apple Watch", "level": 3, "content": [ { "type": "paragraph", "text": "On Apple Watch, Wallet displays passes in a scrolling carousel of cards. People can add your pass to their Apple Watch even if you don’t create a watch-specific app, so it’s important to understand how your pass can look on the device." }, { "type": "paragraph", "text": "People can tap a pass on their Apple Watch to reveal a details screen that displays additional information in a scroll view. In some cases, people can also tap a specific transaction to get more information." }, { "type": "paragraph", "text": "Each pass style specifies the fields and images that can appear in the basic layout areas shown below:" }, { "type": "paragraph", "text": "If some information doesn’t fit within the layout areas, the system displays it in the scrolling details screen." }, { "type": "important", "text": "ImportantIn every style, watchOS crops the strip image to fit the aspect ratio of the card interface and may crop white space from other images." } ] }, { "heading": "Order tracking", "level": 2, "content": [ { "type": "paragraph", "text": "When you support order tracking, Wallet can display information about an order a customer placed through your app or website, updating the information whenever the status of the order changes. In iOS 17 and later, you can help people start tracking their order right from your app or website and offer additional ways to add their order to Wallet." }, { "type": "paragraph", "text": "Wallet presents a dashboard that displays a customer’s active and completed orders. People can choose an order to view details about it, like the items they ordered and fulfillment information for shipping and pickup." }, { "type": "paragraph", "text": "Dashboard" }, { "type": "paragraph", "text": "The Wallet Orders schema defines the properties you use to provide order data like product descriptions, order status, contact information, and shipping and pickup details, including estimated arrival dates, addresses, tracking numbers, and pickup instructions. Wallet displays the information you supply within consistent, system-defined interfaces. To help people get the information they need quickly and conveniently, supply as much information as you can, using the properties that match your order processes." }, { "type": "paragraph", "text": "Make it easy for people to add an order to Wallet. For example, when a customer completes an Apple Pay transaction in your app or website, use PKPaymentOrderDetails (app) or ApplePayPaymentOrderDetails (web) to automatically add the order to Wallet. In iOS 17 and later, you can use AddOrderToWalletButton to display the system-provided Track with Apple Wallet button in relevant areas of your app or website — such as in pages for order confirmation, status, or tracking — or in emails to customers. If a person already added an order to Wallet, trying to add it again opens Wallet and displays the order." }, { "type": "paragraph", "text": "Make information about an order available immediately after people place it. People need to confirm that their order was received, even when payment, processing, and fulfillment are still pending. If you won’t have details until a later time, provide the data you have at the time of the order and supply a status description like “Check back later for full order details.”" }, { "type": "paragraph", "text": "Provide fulfillment information as soon as it’s available, and keep the status up to date. When you supply fulfillment data or you change the status of an order, the system updates the order information and can automatically send a notification to customers. The system uses the fulfillment status you report to update the order’s current status to a value like Order Placed, Processing, Ready for Pickup, Picked Up, Out for Delivery, Delivered, or — if something goes wrong — Issue or Canceled. For guidance on describing a status, see Displaying order and fulfillment details." }, { "type": "paragraph", "text": "Supply a high-resolution logo image that uses a nontransparent background. The system displays your logo image in the dashboard and detail view, so you want to make sure that people can instantly recognize it at various sizes. Use the PNG or JPEG format to create a logo image that measures 300x300 pixels. To help ensure that your logo image renders correctly, be sure to use a nontransparent background. For developer guidance, see logo." }, { "type": "paragraph", "text": "Supply distinct, high-resolution product images that use nontransparent backgrounds. The system displays a product’s image — along with descriptive information you supply — in the detail views, order dashboard, and notifications for an order or a fulfillment. When creating a product image, use a straightforward depiction and a solid, nontransparent background. Showing a product in a “lifestyle” context or against a busy background can make the item hard to distinguish at small sizes. For each product, use the PNG or JPEG format to create an image that measures 300x300 pixels." }, { "type": "paragraph", "text": "In general, keep text brief. People appreciate being able to read text at a glance, and the system can truncate text that’s too long." }, { "type": "paragraph", "text": "Use clear, approachable language, and localize the text you provide. You want to make sure that all your customers can read the information in an order. Also, make sure the price you show matches the final price the customer confirmed." } ] }, { "heading": "Displaying order and fulfillment details", "level": 3, "content": [ { "type": "paragraph", "text": "An order gives people ways to contact the merchant and displays details about their Apple Pay purchase, including fulfillment status and per-item information." }, { "type": "paragraph", "text": "Provide a link to an area where people manage their order. When you provide a universal link, people can open your order management area even if they don’t have your app installed. To learn more about universal links, see Allowing apps and websites to link to your content; for developer guidance, see Order." }, { "type": "paragraph", "text": "Clearly describe each item so people can verify that their order contains everything they expect. You can use the LineItem property to provide information like a product’s price, name, and image. An order lists the line items for every item the customer ordered; a fulfillment lists only the line items that fulfillment includes. When appropriate, you can also attach a PDF receipt to an individual transaction related to an order." }, { "type": "paragraph", "text": "Supply a prioritized list of your apps that might be installed on the device. The system uses this list when it needs to display a link to your app within the order details view. For example, if you provide multiple apps and more than one of them is installed on the device, the system displays a link to the installed app that’s highest on your list. If none of your apps are installed on the device, the system displays a link to the first app on your list. For developer guidance, see Order." }, { "type": "paragraph", "text": "Avoid sending duplicate notifications. For example, you can tell the system to avoid sending order-related notifications through Wallet when the customer has one of your associated apps installed." }, { "type": "paragraph", "text": "Make it easy for customers to contact the merchant. Provide multiple contact methods, so people can choose the one that works best for them. At minimum, you need to provide a link to the merchant’s website or landing page, but you can also provide a Messages for Business link, a phone number, an email address, and a link to a support page. When people choose the Contact button in an order, the system displays a menu of the contact methods you supply. For developer guidance, see Merchant." }, { "type": "paragraph", "text": "Help people track their order. A multi-item order can have multiple fulfillments, where each fulfillment is either shipping or pickup. For example, if a customer orders a pair of shoes and a T-shirt, the customer might want to have one item shipped, while picking up the other. Regardless of fulfillment type, you need to supply enough information for people to know where their items are and when to expect them at the destination they specified. In addition to an estimated time of arrival, here’s some information that people particularly appreciate:" }, { "type": "list", "items": [ "A link that opens the carrier’s website to a page with information about a shipping fulfillment. When possible, provide a direct link — in addition to a tracking number — so people can easily view the most up-to-date shipping information. If necessary, display this link on any intermediate order-tracking page you open.", "A scannable barcode when one is required to pick up the order in a pickup fulfillment. It’s convenient when people can offer the barcode from within Wallet instead of finding it in an email or webpage.", "Clear, detailed instructions that can help people receive or pick up their order." ] }, { "type": "paragraph", "text": "Keep the fulfillment screen centered on order tracking. For example, if you recommend your app or other services to customers, be sure to prioritize order-tracking information over other content in the screen." }, { "type": "paragraph", "text": "Choose shipping-fulfillment values that match the details you have about the shipping process. If you know the carrier, enter its name in the carrier property; otherwise, leave the default “Track Shipment” value. If you can access details about a carrier’s interim shipping steps — such as when a fulfillment is on the way or out for delivery — indicate each step by using specific status values like onTheWay, outForDelivery, or delivered. In contrast, if you don’t have access to a carrier’s shipping details, use the shipped status. In both cases, provide a tracking link (when one is available) so people can track their order on their own. For developer guidance, see ShippingFulfillment." }, { "type": "paragraph", "text": "Keep customers informed through relevant fulfillment status descriptions. A great status message is approachable, accurate, and clearly related to the status it describes. In addition to supplying information that helps people understand the status of their order, a status message also gives you an opportunity to use your brand’s communication style." }, { "type": "paragraph", "text": "Be direct and thorough when describing an Issue or Canceled status. People generally need to know why there’s a problem and what they can do about it." } ] }, { "heading": "Identity verification", "level": 2, "content": [ { "type": "paragraph", "text": "On iPhone running iOS 16 and later, people can store an ID card in Wallet, and later allow an app or App Clip to access information on the card to verify their identity without leaving their current context. For example, a person might need to confirm their identity when they apply for a credit card within their banking app. To learn how to support in-person mobile ID verification, see ID Verifier." }, { "type": "note", "text": "Developer noteApple doesn’t create or see the ID documents that people add to Wallet, and when people agree to share identifying information with your app, you receive only encrypted data that isn’t readable on the device. For developer guidance, see Requesting identity data from a Wallet pass." }, { "type": "paragraph", "text": "To help you offer a consistent experience that people can trust, Apple provides a Verify with Wallet button you can use in your app when you need to ask for identify verification. The button reveals a sheet that describes your request and lets people agree to share their information or cancel." }, { "type": "paragraph", "text": "Present a Wallet verification option only when the device supports it. If the current device can’t return the identify information you request, don’t display a Verify with Apple Wallet button. Be prepared to present a fallback view that offers a different verification method if Verify with Apple Wallet isn’t available; for developer guidance, see VerifyIdentityWithWalletButton." }, { "type": "paragraph", "text": "Ask for identity information only at the precise moment you need it. People can be suspicious of a request for personal information if it doesn’t seem to be related to their current action. If your app needs identity verification, for example, wait to ask for this information until people are completing the process or transaction that requires it; don’t request verification before people are ready to start the process or when they’re simply creating an account." }, { "type": "paragraph", "text": "Clearly and succinctly describe the reason you need the information you’re requesting. You must write text that explains why people need to share identity information with your app (this text is called a purpose string or usage description string). The system displays your purpose string in the verification sheet so people can make an informed decision. Here are a couple of examples:" }, { "type": "table", "rows": [ [ "To verify…", "To support…", "Example purpose string" ], [ "Identity", "Opening an account for which proof of identity is legally required to prevent fraud", "Federal law requires this information to verify your identity and also to help [App Name] prevent fraud." ], [ "Driving privilege", "Renting a vehicle that requires legal driving privileges", "Applicable state law requires [App Name] to verify your driving privileges." ] ] }, { "type": "paragraph", "text": "For each purpose string, aim for a brief, complete sentence that’s direct, specific, and easy for everyone to understand. Use sentence case, avoid passive voice, and include a period at the end." }, { "type": "paragraph", "text": "Ask only for the data you actually need. People may lose trust in your app if you ask for more data than you need to complete the current task or action. For example, if you need to ensure that a customer is at least a certain age, use a request that specifies an age threshold; avoid requesting the customer’s current age or birth date. For developer guidance, see age(atLeast:)." }, { "type": "paragraph", "text": "Clearly indicate whether you will keep the data and — if you need to keep it — specify how long you’ll do so. To help people trust your app, it’s essential to explain how long you might need to keep the personal information they agree to share with you. When you use PassKit APIs to specify a duration — such as a particular period, indefinitely, or only as long as it takes to complete the current verification — the system automatically displays explanatory content in the verification sheet. For developer guidance, see PKIdentityIntentToStore." }, { "type": "paragraph", "text": "Choose the system-provided verification button that matches your use case and the visual design of your app. The system provides the following button labels to support various use cases:" }, { "type": "table", "rows": [ [ "Button type", "Consider using when…" ], [ "", "Your app can complete the current transaction after you verify a person’s age. An example transaction is making a car available to lease." ], [ "", "Your app can complete the current transaction after you verify a person’s identity. An example transaction is a car rental." ], [ "", "Verify with Wallet forms one part of a verification process that also requires people to supply additional information not provided by Verify with Wallet, such as a Social Security number or phone number. Examples include opening a financial account or performing a background check." ], [ "", "Your app can complete the current verification flow without additional steps, but the “Verify Age,” “Verify Identity,” and “Continue” button labels aren’t appropriate for your use case. An example is an app that helps people sign up for a government service." ] ] }, { "type": "paragraph", "text": "All button labels are also available in a multiline variant that the system automatically uses when horizontal space is constrained. For developer guidance, see PKIdentityButton.Label." }, { "type": "paragraph", "text": "The verification button always uses white letters on a black background. You can choose the style that includes a light outline if you need to ensure that the button contrasts well with a dark background in your app. In addition, you can use the cornerRadius property to adjust the verification button’s corners to match other related buttons in your interface. For developer guidance, see PKIdentityButton.Style.blackOutline." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, visionOS, or watchOS. Not supported in tvOS." } ] }, { "heading": "Pass image dimensions", "level": 3, "content": [ { "type": "paragraph", "text": "As you design images for your wallet passes, create PNG files and use the following values for guidance." }, { "type": "table", "rows": [ [ "Image", "Supported pass styles", "Filename", "Dimensions (pt)" ], [ "Logo", "Boarding pass, coupon, store card, event ticket, generic pass", "logo.png", "Any, up to 160x50" ], [ "Primary logo", "Poster event ticket", "primaryLogo.png", "Any, up to 126x30" ], [ "Secondary logo", "Poster event ticket", "secondaryLogo.png", "Any, up to 135x12" ], [ "Icon", "All", "icon.png", "38x38" ], [ "Background", "Event ticket, poster event ticket", "background.png (event ticket), artwork.png (poster event ticket)", "180x220 (event ticket), 358x448 (poster event ticket)" ], [ "Strip", "Coupon, store card, event ticket", "strip.png", "375x144 (coupon, store card), 375x98 (event ticket)" ], [ "Footer", "Boarding pass", "footer.png", "Any, up to 286x15" ], [ "Thumbnail", "Event ticket, generic pass", "thumbnail.png", "90x90" ] ] }, { "type": "note", "text": "NoteDimensions for the logo, primary logo, and secondary logo images are the maximum — not the required — values. For example, if you create a primary logo image that measures 30x30 points, you don’t need to add unnecessary padding so that it measures the maximum 126x30 points." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "Apple Pay" }, { "type": "paragraph", "text": "ID Verifier" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "FinanceKitUI" }, { "type": "paragraph", "text": "FinanceKit" }, { "type": "paragraph", "text": "PassKit (Apple Pay and Wallet)" }, { "type": "paragraph", "text": "Wallet Passes" }, { "type": "paragraph", "text": "Wallet Orders" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "January 17, 2025", "Added specifications for pass image dimensions." ], [ "December 18, 2024", "Added guidance for the poster event ticket style." ], [ "September 12, 2023", "Added guidance for helping people add orders to Wallet." ], [ "February 20, 2023", "Enhanced guidance for presenting order-tracking information and added artwork." ], [ "November 30, 2022", "Added guidance to include a carrier name in status information for a shipping fulfillment." ], [ "September 14, 2022", "Added guidelines for using Verify with Wallet, updated guidance on providing shipping status values and descriptions, and consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Passes", "url": "/design/human-interface-guidelines/wallet#Passes" }, { "title": "Designing passes", "url": "/design/human-interface-guidelines/wallet#Designing-passes" }, { "title": "Passes for Apple Watch", "url": "/design/human-interface-guidelines/wallet#Passes-for-Apple-Watch" }, { "title": "Pass styles", "url": "/design/human-interface-guidelines/wallet#Pass-styles" }, { "title": "Boarding passes", "url": "/design/human-interface-guidelines/wallet#Boarding-passes" }, { "title": "Coupons", "url": "/design/human-interface-guidelines/wallet#Coupons" }, { "title": "Store cards", "url": "/design/human-interface-guidelines/wallet#Store-cards" }, { "title": "Event tickets", "url": "/design/human-interface-guidelines/wallet#Event-tickets" }, { "title": "Generic passes", "url": "/design/human-interface-guidelines/wallet#Generic-passes" }, { "title": "Order tracking", "url": "/design/human-interface-guidelines/wallet#Order-tracking" }, { "title": "Displaying order and fulfillment details", "url": "/design/human-interface-guidelines/wallet#Displaying-order-and-fulfillment-details" }, { "title": "Identity verification", "url": "/design/human-interface-guidelines/wallet#Identity-verification" }, { "title": "ID Verifier", "url": "/design/human-interface-guidelines/id-verifier" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/wallet#Platform-considerations" }, { "title": "Specifications", "url": "/design/human-interface-guidelines/wallet#Specifications" }, { "title": "Pass image dimensions", "url": "/design/human-interface-guidelines/wallet#Pass-image-dimensions" }, { "title": "Resources", "url": "/design/human-interface-guidelines/wallet#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/wallet#Related" }, { "title": "Apple Pay", "url": "/design/human-interface-guidelines/apple-pay" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/wallet#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/wallet#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/wallet#Change-log" } ], "image_count": 0 }, { "title": "iCloud", "url": "https://developer.apple.com/design/human-interface-guidelines/icloud", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "A fundamental aspect of iCloud is transparency. People don’t need to know where content resides. They can just assume they’re always accessing the latest version." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Make it easy to use your app with iCloud. People turn on iCloud in Settings and expect apps to work with it automatically. If you think people might want to choose whether to use iCloud with your app, show a simple option the first time your app opens that provides a choice between using iCloud for all data or not at all." }, { "type": "paragraph", "text": "Avoid asking which documents to keep in iCloud. Most people expect all of their content to be available in iCloud and don’t want to manage the storage of individual documents. Consider how your app handles and exposes content, and try to perform more file-management tasks automatically." }, { "type": "paragraph", "text": "Keep content up to date when possible. In an app that supports iCloud, it’s best when people always have access to the most recent content. However, you need to balance this experience with respect to device storage and bandwidth constraints. If your app works with very large documents, it may be better to let people control when updated content is downloaded. If your app fits in this category, design a way to indicate that a more recent version of a document is available in iCloud. When a document is updating, provide subtle feedback if the download takes more than a few seconds." }, { "type": "paragraph", "text": "Respect iCloud storage space. iCloud is a finite resource for which people pay. Use iCloud to store information people create and understand, and avoid using it for app resources or content you can regenerate. Even if your app doesn’t implement iCloud support, remember that iCloud backups include the contents of every app’s Documents folder. To avoid using up too much space, be picky about the content you place in the Documents folder." }, { "type": "paragraph", "text": "Make sure your app behaves appropriately when iCloud is unavailable. If someone manually turns off iCloud or turns on Airplane Mode, you don’t need to display an alert notifying them iCloud is unavailable. However, it may still be helpful to unobtrusively let people know that changes they make won’t be available on other devices until they restore iCloud access." }, { "type": "paragraph", "text": "Keep app state information in iCloud. In addition to storing documents and other files, you can use iCloud to store settings and information about the state of your app. For example, a magazine app might store the last page viewed so when the app is opened on another device, someone can continue reading from where they left off. If you use iCloud to store settings, make sure it’s for ones people want applied to all of their devices. For example, some settings might be more useful at work than at home." }, { "type": "paragraph", "text": "Warn about the consequences of deleting a document. When someone deletes a document in an app that supports iCloud, the document is removed from iCloud and all other devices too. Show a warning and ask for confirmation before performing the deletion." }, { "type": "paragraph", "text": "Make conflict resolution prompt and easy. To the extent possible, try to detect and resolve version conflicts automatically. If this can’t be done, display an unobtrusive notification that makes it easy to differentiate and choose between the conflicting versions. Ideally, conflict resolution occurs as early as possible, so time isn’t wasted in the wrong version." }, { "type": "paragraph", "text": "Include iCloud content in search results. People with iCloud accounts assume their content is universally available, and they expect search results to reflect this perspective." }, { "type": "paragraph", "text": "For games, consider saving player progress in iCloud. Although you can implement this functionality yourself, the GameSave framework offers an efficient solution. It synchronizes save data across devices and offers built-in alerts you can use to help players handle syncing issues during offline play or when conflicts arise. Alternatively, you can implement custom UI that uses GameSave data to resolve these situations. For developer guidance, see GameSave." } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "CloudKit" }, { "type": "paragraph", "text": "GameSave" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "June 9, 2025", "Added guidance for synchronizing game data through iCloud." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/icloud#Best-practices" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/icloud#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/icloud#Resources" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/icloud#Developer-documentation" }, { "title": "Change log", "url": "/design/human-interface-guidelines/icloud#Change-log" } ], "image_count": 0 }, { "title": "iMessage apps and stickers", "url": "https://developer.apple.com/design/human-interface-guidelines/imessage-apps-and-stickers", "category": "technologies", "summary": "", "sections": [ { "heading": "Overview", "level": 2, "content": [ { "type": "paragraph", "text": "An iMessage app or sticker pack is available within the context of a Messages conversation and also in effects in both Messages and FaceTime. You can create an iMessage app or sticker pack as a standalone app or as an app extension within your iOS or iPadOS app. For developer guidance, see Messages and Adding Sticker packs and iMessage apps to the system Stickers app, Messages camera, and FaceTime." } ] }, { "heading": "Best practices", "level": 2, "content": [ { "type": "paragraph", "text": "Prefer providing one primary experience in your iMessage app. People are in a conversational flow when they choose your app, so your functionality or content needs to be easy to understand and immediately available. If you want to provide multiple types of functionality or different collections of content, consider creating a separate iMessage app for each one." }, { "type": "paragraph", "text": "Consider surfacing content from your iOS or iPadOS app. For example, your iMessage app could offer app-specific information that people might want to share — such as a shopping list or a trip itinerary — or support a simple, collaborative task, like deciding where to go for a meal or which movie to watch." }, { "type": "paragraph", "text": "Present essential features in the compact view. People can experience your iMessage app in a compact view that appears below the message transcript, or they can expand the view to occupy most of the window. Make sure the most frequently used items are available in the compact view, reserving additional content and features for the expanded view." }, { "type": "paragraph", "text": "In general, let people edit text only in the expanded view. The compact view occupies roughly the same space as the keyboard. To ensure that the iMessage app’s content remains visible while people edit, display the keyboard in the expanded view." }, { "type": "paragraph", "text": "Create stickers that are expressive, inclusive, and versatile. Whether your stickers are rich, static images or short animations, make sure that each one remains legible against a wide range of backgrounds and when rotated or scaled. You can also use transparency to help people visually integrate a sticker with text, photos, and other stickers." }, { "type": "paragraph", "text": "For each sticker, provide a localized alternative description. VoiceOver can help people use your sticker pack by speaking a sticker’s alternative description." } ] }, { "heading": "Icon sizes", "level": 3, "content": [ { "type": "paragraph", "text": "The icon for an iMessage app or sticker pack can appear in Messages, the App Store, notifications, and Settings. After people install your iMessage app or sticker pack, its icon also appears in the app drawer in the Messages app." }, { "type": "paragraph", "text": "You supply a square-cornered icon for each extension you offer, and the system automatically applies a mask that rounds the corners." }, { "type": "paragraph", "text": "To ensure that your icon looks great in any context and on various devices, create a square-cornered icon in the following sizes:" }, { "type": "table", "rows": [ [ "Usage", "@2x (pixels)", "@3x (pixels)" ], [ "Messages, notifications", "148x110", "-" ], [ "", "143x100", "-" ], [ "", "120x90", "180x135" ], [ "", "64x48", "96x72" ], [ "", "54x40", "81x60" ], [ "Settings", "58x58", "87x87" ], [ "App Store", "1024x1024", "1024x1024" ] ] } ] }, { "heading": "Sticker sizes", "level": 3, "content": [ { "type": "paragraph", "text": "Messages supports small, regular, and large stickers. Pick the size that works best for your content and prepare all of your stickers at that size; don’t mix sizes within a single sticker pack. Messages displays stickers in a grid, organized differently for different sizes." }, { "type": "paragraph", "text": "Small" }, { "type": "paragraph", "text": "Regular" }, { "type": "paragraph", "text": "Large" }, { "type": "paragraph", "text": "Create your sticker images using the following @3x dimensions for the sticker size you chose. If necessary, the system generates @2x and @1x versions by downscaling the images at runtime. For developer guidance, see MSStickerSize." }, { "type": "table", "rows": [ [ "Sticker size", "@3x dimensions (pixels)" ], [ "Small", "300x300" ], [ "Regular", "408x408" ], [ "Large", "618x618" ] ] }, { "type": "paragraph", "text": "A sticker file must be 500 KB or smaller in size. For each supported format, the table below provides guidance for using transparency and animation." }, { "type": "table", "rows": [ [ "Format", "Transparency", "Animation" ], [ "PNG", "8-bit", "No" ], [ "APNG", "8-bit", "Yes" ], [ "GIF", "Single-color", "Yes" ], [ "JPEG", "No", "No" ] ] } ] }, { "heading": "Platform considerations", "level": 2, "content": [ { "type": "paragraph", "text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS." } ] }, { "heading": "Related", "level": 4, "content": [ { "type": "paragraph", "text": "iMessage Apps and Stickers" } ] }, { "heading": "Developer documentation", "level": 4, "content": [ { "type": "paragraph", "text": "Messages" }, { "type": "paragraph", "text": "Adding Sticker packs and iMessage apps to the system Stickers app, Messages camera, and FaceTime — Messages" } ] }, { "heading": "Change log", "level": 2, "content": [ { "type": "table", "rows": [ [ "Date", "Changes" ], [ "May 2, 2023", "Consolidated guidance into one page." ] ] } ] } ], "platforms": [], "related": [ { "title": "Best practices", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Best-practices" }, { "title": "Specifications", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Specifications" }, { "title": "Icon sizes", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Icon-sizes" }, { "title": "Sticker sizes", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Sticker-sizes" }, { "title": "Platform considerations", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Platform-considerations" }, { "title": "Resources", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Resources" }, { "title": "Related", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Related" }, { "title": "Developer documentation", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Developer-documentation" }, { "title": "Videos", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Videos" }, { "title": "Change log", "url": "/design/human-interface-guidelines/imessage-apps-and-stickers#Change-log" } ], "image_count": 0 } ] }