روشی مطمئن‌تر برای افزودن و ویرایش مخاطبین در Android

چه چیزی تغییر می‌کند

برنامه‌هایی که نسخه آتی Android را هدف قرار می‌دهند دیگر نمی‌توانند بااجازه WRITE_CONTACTS مستقیماً در مخاطبین بنویسند. درعوض، می‌توانید از هدف‌های مخاطب استاندارد (ACTION_INSERT، ACTION_EDIT، و ACTION_INSERT_OR_EDIT) استفاده کنید. برای پیاده‌سازی مرجع کامل، راهنمای توسعه‌دهنده را درباره نحوه اصلاح مخاطبین بااستفاده از هدف‌ها ببینید. 

در دستگاه‌هایی که نسخه آتی Android را اجرا می‌کنند، این سه هدف مخاطب به‌طور هماهنگ رفتار خواهند کرد و اصلاً به هیچ اجازه‌ای نیاز ندارند. اگر برنامه شما نسخه آتی Android یا نسخه‌های جدیدتر را هدف قرار دهد و تلاش کند مستقیماً در مخاطبین بنویسد، این نوشتن‌ها رد خواهد شد و منجر به SecurityException یا رد اجازه خواهد شد. برای مجموعه کوچکی از برنامه‌ها که برای ایجاد و اصلاح مخاطبین به دسترسی گسترده نیاز دارند، اجازه دسترسی ویژه جدیدی به برنامه، MANAGE_CONTACTS، در Android 17 QPR2 (سه‌ماهه چهارم ۲۰۲۶) ارائه می‌شود. Google Play امروز دستورالعمل‌های به‌روزشده‌ای را برای دسترسی به مخاطبین، ازجمله MANAGE_CONTACTS، منتشر می‌کند.

چرا این کار را انجام می‌دهیم

درحال‌حاضر، اگر برنامه‌تان نیاز به ذخیره حتی یک مخاطب داشته باشد، ممکن است WRITE_CONTACTS را درخواست کنید. اما این اجازه دسترسی گسترده‌ای را اعطا می‌کند و به برنامه اجازه می‌دهد تغییرات گسترده‌ای در مخاطبین سراسر دستگاه در پس‌زمینه ایجاد کند، حتی بدون تعامل کاربر. اکثر برنامه‌ها به چنین اجازه گسترده‌ای نیاز ندارند.

درحالی‌که جایگزین‌هایی وجود دارد، از شما شنیده‌ایم که این جایگزین‌ها باید در سراسر بوم‌سازگان استانداردتر شوند. قبلاً، هدف‌های مخاطب در دستگاه‌های مختلف متفاوت عمل می‌کردند. برخی‌از ویرایشگرها داده‌هایی را که وارد کرده‌اید، مثل عکس مخاطب، حذف کردند. در برخی‌از دستگاه‌ها، دکمه برگشتن مخاطب را بدون قصد کاربر ذخیره می‌کرد یا گزینه «ایجاد مخاطب جدید» به‌سختی پیدا می‌شد. بنابراین درخواست اجازه انتخاب منطقی بود. ما همه این مشکلات را در نسخه آتی Android برطرف می‌کنیم و دستگاه‌هایی را که از آن استفاده می‌کنند ملزم می‌کنیم از همین استانداردها پیروی کنند.

به‌جای آن از چه چیزی استفاده کنید

افزودن یا ویرایش مخاطب: از هدف‌های مخاطب استفاده کنید

وقتی از این هدف‌ها (ACTION_INSERT، ACTION_EDIT، و ACTION_INSERT_OR_EDIT) استفاده می‌کنید، سیستم با ارائه تجربه ویرایشگر مخاطب تمیز و استاندارد، کارهای سنگین را انجام می‌دهد. این دکمه فرم نیم‌برگ سریعی را برای ورودی‌های جدید باز می‌کند یا به کاربر اجازه می‌دهد به‌راحتی اطلاعاتی را جستجو کند و به مخاطب موجود اضافه کند. کاربران می‌توانند به‌طور یکپارچه این را به یک ویرایشگر تمام‌صفحه گسترش دهند تا جزئیات بیشتری را پر کنند، بدون اینکه برنامه شما به اجازه‌های نوشتن مستقیم نیاز داشته باشد. نمونه‌های آزمایشی تجربه کاربری را در زیر ببینید: 

شکل ۱: ایجاد مخاطب جدید  *تجربه کاربری نهایی نیست*

شکل ۲: افزودن اطلاعات به مخاطب موجود *تجربه کاربری نهایی نیست*

توجه: سازندگان مختلف دستگاه ممکن است تجربه کاربری را برای مطابقت با سبک سیستم‌عامل خود تغییر دهند، اما رفتار ثابت باقی خواهد ماند.

می‌توانید با ارسال بار داده‌های اختیاری، که به‌عنوان «موارد اضافی» شناخته می‌شوند، در کنار قصدتان، فرایند ایجاد را بیشتر ساده کنید:

• 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 (سه‌ماهه چهارم ۲۰۲۶) ارائه می‌شود. این یک دایرکتوری سیستم جدید است که در آن برنامه شما نحوه دسترسی افراد به یکدیگر را در برنامه شما منتشر می‌کند، بدون اینکه مخاطبین کاربر را ویرایش کند.

نمونه‌هایی از نحوه انتقال برنامه‌ها

برای اینکه ببینید این جایگزین‌ها در عمل چگونه کار می‌کنند، در اینجا چند نمونه از نحوه رویکرد انواع مختلف برنامه‌ها به دسترسی به مخاطبین آورده شده است:

تغییراتی که باید بررسی شود

• انواع داده‌های سفارشی در ویرایشگر پشتیبانی نمی‌شوند. اگر ردیف‌های Insert.DATA را با انواع رسانه غیر از انواع استاندارد ContactsContract.CommonDataKinds ارسال کنید، ویرایشگر آن انواع رسانه را بدون اطلاع نادیده می‌گیرد.
• SHOW_OR_CREATE_CONTACT توسط ویرایشگر سیستم مدیریت نمی‌شود. برنامه‌های مخاطبین که با دستگاه ارائه می‌شوند همچنان می‌توانند آن را مدیریت کنند. برای رفتار یکسان در همه دستگاه‌ها، از ACTION_INSERT_OR_EDIT استفاده کنید.
• نوشتن به‌طور پیش‌فرض ناموفق است. وقتی نسخه آتی Android را هدف قرار می‌دهید، هرگونه نوشتن مستقیم بدون MANAGE_CONTACTS منجر به SecurityException or permission denial می‌شود. آزمایش کنید.

آیا به MANAGE_CONTACTS نیاز دارم؟

احتمالاً نه. اگر برنامه‌تان مخاطبین را به‌درخواست کاربر ذخیره یا ویرایش می‌کند، هدف‌های بالا شما را پوشش می‌دهند، بدون اینکه به اجازه و اظهارنامه «کنسول Play» نیاز باشد.

‫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» ارسال کنید و توضیح دهید چرا هدف‌ها برای عملکرد اصلی برنامه‌تان کافی نیستند.

مراحل انتقال

• نوشته‌های مخاطب را پیدا کنید. کدتان را برای 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» خود را برنامه‌ریزی کنید.
• وقتی هیچ مسیر کدی به  WRITE_CONTACTS نیاز نداشت، آن را از مانیفست بردارید.

خط زمان

پرسشگان

• آیا این موضوع بر همه برنامه‌ها تأثیر می‌گذارد؟
  • تغییر منسوخ شدن WRITE_CONTACTS فقط برای برنامه‌هایی اعمال می‌شود که نسخه آتی Android و نسخه‌های بعداز آن را هدف قرار می‌دهند. برنامه‌هایی که نسخه‌های قدیمی‌تر را هدف قرار می‌دهند رفتار فعلی‌شان را حفظ می‌کنند، اما ویرایشگر مخاطب استانداردشده جدید برای همه برنامه‌هایی که در سیستم‌عامل جدید اجرا می‌شوند دردسترس خواهد بود، صرف‌نظر از اینکه کیت توسعه نرم‌افزار هدف آن‌ها چه باشد.
• آیا برنامه‌ام می‌تواند مخاطبین را با قصد حذف کند؟
  • نه. قصدی برای حذف مخاطبین وجود ندارد. کاربران مخاطبین را در برنامه مخاطبین خود حذف می‌کنند. برنامه‌های دارای MANAGE_CONTACTS می‌توانند مخاطبین را مستقیماً حذف کنند.
• ازقبل صفحه ویرایش مخاطب خودم را دارم. می‌توانم آن را نگه دارم؟
  • فقط اگر برنامه‌تان واجدشرایط MANAGE_CONTACTS باشد. تمایل به حفظ طراحی سفارشی به‌تنهایی دلیل واجدشرایط بودن نیست.
• آیا MANAGE_CONTACTS جایگزین READ_CONTACTS می‌شود؟
  • MANAGE_CONTACTS شامل دسترسی خواندن است، بنابراین نیازی نیست هر دو را درخواست کنید، اما بسیاری از برنامه‌ها واجدشرایط READ_CONTACTS هستند که اصلاً نیازی به تغییر مخاطبین ندارند. این برنامه‌ها ممکن است همچنان READ_CONTACTS را درخواست کنند.
• کاربران من که از نسخه‌های قدیمی‌تر Android استفاده می‌کنند چه می‌شوند؟
  • هدف‌های مخاطب در نسخه‌های قدیمی‌تر نیز کار می‌کنند و توسط برنامه مخاطبین دستگاه مدیریت می‌شوند. اکثر برنامه‌ها بااستفاده از این هدف‌ها در همه دستگاه‌ها به‌خوبی کار خواهند کرد. اگر برنامه‌تان تحت‌تأثیر مشکل سازگاری خاصی قرار گرفته است که فقط در جدیدترین نسخه‌ها حل شده است، می‌توانید اجازه WRITE_CONTACTS را در مانیفست خود با maxSdkVersion مناسب نگه دارید.