[Platform deprecation][Google] Add Android Contact Picker before 2027-01-27

[shai-almog]

Impact summary

Urgency: High. From 2027-01-27, Google Play policy requires apps targeting Android 17 (API level 37)+ to use the Android Contact Picker when broad READ_CONTACTS access is not essential to core functionality. Apps retaining broad access must pass a Play Console declaration explaining why the picker is insufficient.

Codename One's public contact-reading APIs currently expose only broad address-book access. Referencing them causes the generated manifest to request READ_CONTACTS, and the Android port requests that runtime permission before every read. CN1 users who only need a user-selected contact have no policy-minimized framework path.

Official requirement and deadline

• Google Play policy deadlines: https://support.google.com/googleplay/android-developer/table/12921780
  • Announced 2026-04-15; exact deadline 2027-01-27.
  • Apps that do not need broad access must use the Android Contact Picker.
• Detailed contacts permission policy: https://support.google.com/googleplay/android-developer/answer/16935362
  • September 2026: Play Console begins prompting apps carrying READ_CONTACTS to submit a declaration or remove the permission and use the picker.
  • Applies to apps targeting Android 17 / API 37+; after the deadline, noncompliant apps are subject to enforcement. A 30-day extension is available in Play Console.
• Android Contact Picker implementation guide: https://developer.android.com/about/versions/17/features/contact-picker
  • Page last updated 2026-07-14 UTC.
  • ContactsPickerSessionContract.ACTION_PICK_CONTACTS grants temporary access only to contacts/fields selected by the user; the picker is available on Android 17+.

Hard policy enforcement deadline: 2027-01-27.

First affected platform/store combination: Google Play apps targeting Android 17 / API 37+ that request READ_CONTACTS without an approved core-functionality justification.

Concrete Codename One applicability

Verified against codenameone/CodenameOne master at 134f6ec227792da11b595a77eda6c06d3c0a2b8f:

• Ports/Android/src/com/codename1/impl/android/AndroidImplementation.java
  • getAllContacts(...), getContactById(...), and related methods call checkForPermission(Manifest.permission.READ_CONTACTS, ...) before delegating to AndroidContactsManager.
• Ports/Android/src/com/codename1/impl/android/AndroidContactsManager.java
  • Reads directly from ContactsContract.Contacts, ContactsContract.Data, phone, email, address, birthday, and note tables using ContentResolver.
• maven/codenameone-maven-plugin/src/main/java/com/codename1/builders/AndroidGradleBuilder.java
  • Detects contact API use and emits <uses-permission android:name="android.permission.READ_CONTACTS" ...> into the generated manifest.
• codenameone/BuildDaemon master at 09cd713c6abe9455d0574ed0a1ff0776bee84754
  • AndroidBuilder and AndroidGradleBuilder mirror the same READ_CONTACTS permission injection in hosted builds.
• No ContactsPickerSessionContract, ACTION_PICK_CONTACTS, or Contact Picker result handling exists on the default branch.

Deduplication across open and closed issues/PRs used Contact Picker, READ_CONTACTS, API 37, 2027-01-27, and the official notice name. No tracking item or completed migration was found.

Affected users and failure mode

• CN1 apps targeting API 37+ that use Display.getAllContacts(), getContactById(), or equivalent broad read APIs.
• Apps that only need one or a few user-selected phone numbers, email addresses, or postal addresses cannot currently choose the policy-minimized picker path.
• Failure mode: Play Console declaration/review burden; update rejection or policy enforcement if broad access is not accepted as core functionality; or loss of the contact feature if users remove READ_CONTACTS without a replacement API.

Proposed migration

1. Investigation/API design
   • Define a cross-platform contact-selection API with explicit requested fields, single/multiple selection, cancellation, and temporary-result semantics.
   • Separate picker use from existing broad address-book management APIs so existing valid CRM/contact-manager cases remain possible.
2. Implementation
   • On Android 17+, launch ContactsPickerSessionContract.ACTION_PICK_CONTACTS, request only selected MIME fields, parse the session URI, and copy required values before temporary access expires.
   • Provide a documented compatible fallback on older Android versions, using system selection where possible.
   • Ensure picker-only apps do not receive READ_CONTACTS; keep broad permission injection only for broad APIs.
   • Mirror builder/generated-project changes in BuildDaemon.
3. CI and beta validation
   • Unit-test API result mapping, cancellation, multi-select, requested-field filtering, and temporary URI handling.
   • Add generated-manifest tests proving picker-only use omits READ_CONTACTS while broad APIs still inject it.
   • Run Android 17 emulator/device tests across personal/work profiles and old-version fallback tests.
4. Release and communication
   • Release framework, Maven builder, and BuildDaemon support together.
   • Document which APIs require a Play declaration and provide a migration example from broad reads to user-selected contacts.

Internal target dates

• 90-day checkpoint / API design approved: 2026-10-29
• 60-day checkpoint / implementation complete: 2026-11-28
• CI, Android 17 beta, and hosted-build validation complete: 2026-12-14
• Release and customer communication no later than 2026-12-28, preserving the required 30-day buffer before 2027-01-27 enforcement

Risks, unknowns, and verification plan

• Contact Picker is Android 17-only and session URIs are temporary; lifecycle/process-death behavior must be tested.
• The framework must not silently turn a narrow picker call into broad permission access on older releases.
• CN1's existing Contact model may not express partial-field/multiple-selection provenance cleanly; settle that before freezing the API.
• BuildCloud must have an API 37-capable toolchain before compiling direct Android 17 symbols, or the implementation must use a compatible AndroidX/reflection boundary until that image ships.
• Verify a release AAB in Play Console's pre-launch/policy checks, plus Android 17 personal/work-profile selection and API 23-36 fallback behavior.