sodcalculator

10 Tech How-To

iOS Keyboard Extensions: App Context Handling

Guide 10-52578 · Updated · Step by step

This guide explains how iOS keyboard extensions (custom keyboards) detect and use the app they are running in, letting you tailor suggestions, layouts, or actions to the current context. You’ll learn the system’s built-in mechanisms and how to read them correctly. Before starting, you need a basic understanding of Swift, Xcode, and the iOS Keyboard Extension template.

What You’ll Need

  • Xcode (latest stable version)
  • An Apple Developer account (free tier works for local testing)
  • A physical iOS device or simulator (simulator is fine for most context checks)
  • Basic familiarity with Swift and the iOS Keyboard Extension template

Step-by-Step

  1. Understand the two context layers. iOS gives your keyboard extension two distinct ways to see the host app: the parentViewController (which is usually an internal system container, not the actual app) and the textDocumentProxy (which provides limited info about the text field). The primary reliable context signal is the UITextContentType and the keyboard’s returnKeyType — not the app’s bundle identifier.
  2. Read the text content type. In your UIInputViewController subclass, access textDocumentProxy and check its contentType property. For example, if the user is in an email field, contentType is .emailAddress. Use this to change your keyboard’s suggestion bar or key labels.
  3. Check the return key type. The returnKeyType on the proxy tells you what the system expects (e.g., .go, .search, .send). Adjust your keyboard’s return key label to match — this is a simple, reliable context cue.
  4. Use the keyboard appearance and traits. The proxy’s keyboardAppearance (light/dark) and keyboardType (e.g., .numberPad, .URL) give further hints. For a URL field, you might show a “.com” key; for a number pad, you might show a numeric layout.
  5. Detect secure text entry. Check textDocumentProxy.isSecureTextEntry. If true, disable features like autocorrect, word suggestions, or any logging — this is critical for password fields.
  6. Handle the app switch notification. When the user switches to a different app, your extension may be reloaded. Override viewWillAppear and re-read the proxy’s properties there. Do not cache context across appearances.
  7. Use the requestOpenURL method (with caution). If you need to pass context to your containing app, use openURL from the extension context. This only works if the user has granted “Full Access” and your containing app declares the URL scheme. Include a fallback message if Full Access is off.
  8. Test with real apps. Simulator gives you limited context. On a physical device, open Safari, Messages, Notes, and a password manager to see how your keyboard behaves in each. Use the Debug > Attach to Process feature in Xcode to inspect the proxy values live.

Common Mistakes

  • Relying on the bundle identifier. The parentViewController is not the host app; it’s a system container. Trying to read the app’s bundle ID from there is unreliable and often returns a system identifier, not the actual app.
  • Assuming context is static. The proxy’s properties can change while the keyboard is open (e.g., user taps a different field). Always re-read them on every keystroke or selection change, not just at launch.
  • Ignoring Full Access. Many context features (like network requests or openURL) require the user to enable Full Access in Settings. If you don’t check for it, your features will silently fail.
  • Overriding the system’s return key. If you set your own return key label without respecting returnKeyType, users may press a “Search” key in a chat field and expect the wrong action.

Tips

  • Combine signals. Use contentType + keyboardType + returnKeyType together to infer the field’s purpose. For example, .emailAddress + .emailAddress keyboard + .next return key almost certainly means a login form.
  • Keep a lightweight context model. Create a struct that holds the current field type, return key, and secure flag. Update it in one place, then use it to drive UI changes.
  • Respect user expectations. If the user is in a search field, show a magnifying glass icon on the return key. If in a chat field, show a send arrow. This small touch dramatically improves perceived quality.
  • Test accessibility. VoiceOver reads the return key label. If you change it, make sure the accessibility label matches.

Troubleshooting

  • Context is always nil or wrong. Make sure you are reading from textDocumentProxy, not parentViewController. Also, in the simulator, some content types are not set — test on a device.
  • Your keyboard reloads on every app switch. That’s normal. Move your context-reading code to viewWillAppear and avoid expensive setup there.
  • Full Access is off, but you need it. Show a clear message and a button that opens Settings using UIApplication.openSettingsURLString (from the containing app, not the extension).
  • The return key label doesn’t change. Check if you are using a custom input view. If you are, you must manually update the label based on returnKeyType — the system won’t do it for you.
  • Your keyboard crashes when accessing the proxy. Ensure you only call proxy methods when the keyboard is active and the proxy is non-nil. Wrap access in a guard statement.

Frequently Asked Questions

Can I get the host app’s bundle identifier? No, not reliably. Apple deliberately hides it. Use content types and keyboard traits instead.

Does the keyboard extension have access to the host app’s data? No, each extension runs in its own sandbox. You can only share data with your containing app via App Groups.

What is the difference between textDocumentProxy and parentViewController? The proxy is your interface to the text field; the parent view controller is a system container that manages the keyboard’s view. Use the proxy for context.

How do I know if the user is in a password field? Check isSecureTextEntry. If true, disable autocorrect and suggestions.

Can I change my keyboard layout based on the app? You can’t detect the app, but you can change layout based on keyboardType (e.g., number pad vs. default).

Do I need Full Access for context detection? No, reading the proxy’s properties works without Full Access. Full Access is only needed for network requests, openURL, and shared storage.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →