Более надежный способ добавлять и изменять контакты на Android

Что произойдет с классической версией Аналитики

Приложения, предназначенные для предстоящего выпуска Android, больше не смогут напрямую записывать данные в контакты с разрешением WRITE_CONTACTS. Вместо этого можно использовать стандартные интенты для контактов (ACTION_INSERT, ACTION_EDIT и ACTION_INSERT_OR_EDIT). Полный пример реализации приведен в руководстве для разработчиков по изменению контактов с помощью намерений. 

На устройствах с предстоящим выпуском Android эти три намерения будут работать одинаково и не потребуют никаких разрешений. Если ваше приложение предназначено для предстоящего выпуска Android или более поздней версии и пытается напрямую записывать данные в контакты, эти записи будут отклонены и приведут к ошибке SecurityException или отказу в разрешении. Для небольшого числа приложений, которым требуется широкий доступ для создания и изменения контактов, в Android 17 QPR2 (IV квартал 2026 г.) появится новое специальное разрешение MANAGE_CONTACTS. Сегодня Google Play публикует обновленные правила доступа к контактам, в том числе MANAGE_CONTACTS.

Зачем нужны изменения

Сейчас, если приложению нужно сохранить хотя бы один контакт, вы можете запрашивать разрешение WRITE_CONTACTS. Однако это разрешение предоставляет широкий доступ, позволяя приложению вносить масштабные изменения в контакты на устройстве в фоновом режиме, даже без взаимодействия с пользователем. Большинству приложений не требуется такое широкое разрешение.

Хотя альтернативы существуют, вы сообщили нам, что они должны быть более стандартизированы в экосистеме. Раньше намерения, связанные с контактами, обрабатывались по-разному на разных устройствах. Некоторые редакторы удаляли переданные вами данные, например фото контакта. На некоторых устройствах кнопка "Назад" сохраняла контакт без ведома пользователя, а функцию "Создать контакт" было трудно найти. Поэтому спросить разрешения было рациональным выбором. Мы устраняем все эти проблемы в следующей версии Android и требуем, чтобы устройства, на которых она работает, соответствовали тем же стандартам.

Что использовать вместо этого

Добавление или изменение контакта: использование намерений

Когда вы используете эти интенты (ACTION_INSERT, ACTION_EDIT и ACTION_INSERT_OR_EDIT), система берет на себя основную работу,  предоставляя понятный и стандартизированный интерфейс редактора контактов. Откроется форма, в которой можно создать новую запись или найти существующий контакт и добавить в него информацию. Пользователи могут развернуть его в полностраничный редактор, чтобы указать больше сведений. При этом вашему приложению не потребуются разрешения на запись. Ниже приведены предварительные макеты UX.

Рисунок 1.Создание контакта.  Интерфейс может измениться.

Рисунок 2.Добавление информации в существующий контакт. *Интерфейс в разработке*

Примечание. Производители устройств могут изменять интерфейс в соответствии со стилем ОС, но поведение останется прежним.

Вы можете дополнительно упростить процесс создания, передав вместе с намерением необязательные полезные данные, известные как Extras:

• EXTRA_ACCOUNT предлагает аккаунт, в котором будет сохранен контакт. Это полезно, если приложение синхронизирует контакты. Это дополнение уже существовало, но поддерживалось не на всех устройствах. Начиная со следующего выпуска Android, поддержка будет стандартизирована для всех устройств.
• EXTRA_PHOTO_URI передает фотографию, чтобы заранее загрузить данные для фото контакта. Редактор обрабатывает разрешение на чтение URI. Это новая функция, которая появится в следующем выпуске Android и будет поддерживаться во всей экосистеме.

// Requires android.permission.WRITE_CONTACTS
fun saveContactDirectly(context: Context, name: String, phone: String, account: Account) {
    val ops = arrayListOf(
        ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI)
            .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, account.type)
            .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, account.name)
            .build(),
        ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(
                ContactsContract.Data.MIMETYPE,
                ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE
            )
            .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name)
            .build(),
        ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI)
            .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0)
            .withValue(
                ContactsContract.Data.MIMETYPE,
                ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE
            )
            .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
            .build()
    )
    context.contentResolver.applyBatch(ContactsContract.AUTHORITY, ops)
}

fun saveContactWithEditor(
    context: Context,
    name: String,
    phone: String,
    account: Account,
    photoUri: Uri
) {
    val intent = Intent(Intent.ACTION_INSERT, ContactsContract.Contacts.CONTENT_URI).apply {
        putExtra(ContactsContract.Intents.Insert.NAME, name)
        putExtra(ContactsContract.Intents.Insert.PHONE, phone)
        // Suggest which account the contact is saved to
        putExtra(ContactsContract.Intents.Insert.EXTRA_ACCOUNT, account)
        // New in the upcoming Android release: pre-fill the contact photo
        putExtra(ContactsContract.Intents.Insert.EXTRA_PHOTO_URI, photoUri)
        clipData = ClipData.newRawUri("", photoUri)
        addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
    }
    context.startActivity(intent)
}

// Requires android.permission.WRITE_CONTACTS
fun addPhoneDirectly(context: Context, rawContactId: Long, phone: String) {
    val values = ContentValues().apply {
        put(ContactsContract.Data.RAW_CONTACT_ID, rawContactId)
        put(ContactsContract.Data.MIMETYPE, ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE)
        put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone)
    }
    context.contentResolver.insert(ContactsContract.Data.CONTENT_URI, values)
}

fun addPhoneWithEditor(context: Context, phone: String) {
    val intent = Intent(Intent.ACTION_INSERT_OR_EDIT).apply {
        type = ContactsContract.Contacts.CONTENT_ITEM_TYPE
        putExtra(ContactsContract.Intents.Insert.PHONE, phone)
    }
    context.startActivity(intent)
}

fun editKnownContact(context: Context, contactUri: Uri, phone: String) {
    val intent = Intent(Intent.ACTION_EDIT, contactUri).apply {
        putExtra(ContactsContract.Intents.Insert.PHONE, phone)
    }
    context.startActivity(intent)
}

Как выбрать контакт с помощью инструмента выбора контактов

Если вам нужно только читать контакты, выбранные пользователем, используйте инструмент выбора контактов, доступный начиная с Android 17. Разрешение не требуется.

Приложения для звонков и мессенджеры: используйте каталог пользователей

Некоторые приложения добавляют в контакты действия "Позвонить через…" или "Написать через…", чтобы пользователи могли начать звонок или чат из приложения "Телефон" или приложения "Контакты". Если ваше приложение делает это, добавляя дополнительные записи в контакты пользователя, перейдите на Каталог контактов, который появится в Android QPR2 (четвертый квартал 2026 года). Это новый системный каталог, в котором ваше приложение публикует информацию о том, как пользователи могут связаться друг с другом в вашем приложении, не редактируя контакты пользователя.

Примеры перехода приложений

Чтобы показать, как эти альтернативы работают на практике, мы подготовили несколько примеров того, как разные типы приложений могут запрашивать доступ к контактам.

Что нужно проверить

• Специальные типы данных в редакторе не поддерживаются. Если вы передадите строки Insert.DATA с MIME-типами, отличными от стандартных типов ContactsContract.CommonDataKinds, эти MIME-типы будут проигнорированы редактором.
• SHOW_OR_CREATE_CONTACT не обрабатывается системным редактором. Предустановленное приложение "Контакты" по-прежнему может обрабатывать это действие. Чтобы обеспечить единообразное поведение на разных устройствах, используйте ACTION_INSERT_OR_EDIT.
• По умолчанию запись не выполняется. Если вы выберете в качестве целевой версии предстоящий выпуск Android, любая прямая запись без MANAGE_CONTACTS приведет к SecurityException or permission denial. Проверьте это.

Нужно ли мне использовать MANAGE_CONTACTS?

Вряд ли. Если ваше приложение сохраняет или редактирует контакты по запросу пользователя, то указанные выше намерения позволяют делать это без разрешения и декларации в Play Console.

MANAGE_CONTACTS – для приложений, основное назначение которых – управление контактами, когда интентов недостаточно. Пример:

Принципы работы

• MANAGE_CONTACTS – это специальное разрешение для приложений. Это не диалоговое окно среды выполнения. Пользователи могут включить его в разделе Настройки > Специальный доступ для приложений > Управление контактами.

// Opens Settings > Apps > Special app access > Manage contacts
val intent = Intent(Settings.ACTION_MANAGE_CONTACTS, Uri.fromParts("package", packageName, null))
context.startActivity(intent)

• Она позволяет читать, добавлять, изменять и удалять контакты, аккаунты и данные каталога пользователей. Запрашивать разрешение READ_CONTACTS не нужно.
• Чтобы опубликовать в Google Play приложение с разрешением MANAGE_CONTACTS, отправьте в Play Console декларацию, в которой объясняется, почему намерений недостаточно для работы основных функций.

Этапы перехода

• Найдите записи контактов. Найдите в коде WRITE_CONTACTS, ContactsContract.RawContacts.CONTENT_URI, ContactsContract.Data.CONTENT_URI и applyBatch(ContactsContract.AUTHORITY, …).
• Замените каждую запись, инициированную пользователем, намерением: ACTION_INSERT для новых контактов и ACTION_EDIT или ACTION_INSERT_OR_EDIT для обновлений.
• Используйте только стандартные типы данных в Insert.DATA. Переместите действия, связанные со звонками и сообщениями, в каталог пользователей.
• Решите, действительно ли вам нужен MANAGE_CONTACTS, используя таблицу выше. Если да, запланируйте заполнение декларации в Play Console.
• Удалите WRITE_CONTACTS из манифеста, когда это разрешение больше не будет требоваться ни для одного пути выполнения.

Хронология

Часто задаваемые вопросы

• Это касается всех приложений?
  • Прекращение поддержки WRITE_CONTACTS затронет только приложения, предназначенные для следующей версии Android и более поздних. Приложения, предназначенные для более ранних версий, сохранят текущее поведение, однако новый стандартизированный редактор контактов будет доступен для всех приложений, работающих на новой ОС, независимо от их целевого SDK.
• Может ли мое приложение удалять контакты с помощью намерения?
  • Нет. Намерение удалить контакты отсутствует. Пользователи удаляют контакты в приложении "Контакты". Приложения с разрешением MANAGE_CONTACTS могут удалять контакты напрямую.
• У меня уже есть собственный экран редактирования контактов. Можно ли ее сохранить?
  • Только если ваше приложение соответствует требованиям MANAGE_CONTACTS. Желание сохранить собственный дизайн не является достаточным основанием.
• Заменяет ли MANAGE_CONTACTS разрешение READ_CONTACTS?
  • Разрешение MANAGE_CONTACTS включает доступ на чтение, поэтому запрашивать оба разрешения не нужно. Однако многим приложениям, которые соответствуют требованиям для получения разрешения READ_CONTACTS, не нужно изменять контакты. Эти приложения могут по-прежнему запрашивать READ_CONTACTS.
• Что произойдет с пользователями более ранних версий Android?
  • Намерения для контактов работают и в более ранних версиях, обрабатываемых приложением "Контакты" на устройстве. Большинство приложений будут хорошо работать на всех устройствах, использующих эти намерения. Если в вашем приложении есть проблема с согласованностью, которая решена только в последних версиях, вы можете оставить разрешение WRITE_CONTACTS в манифесте, указав подходящее значение maxSdkVersion.