هدف‌های مشترک

val REQUEST_IMAGE_CAPTURE = 1

private fun dispatchTakePictureIntent() {
    val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE)
    } catch (e: ActivityNotFoundException) {
        // Display error state to the user.
    }
}

static final int REQUEST_IMAGE_CAPTURE = 1;

private void dispatchTakePictureIntent() {
    Intent takePictureIntent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE);
    } catch (ActivityNotFoundException e) {
        // Display error state to the user.
    }
}
</section></div>

برای کسب اطلاعات بیشتر درباره نحوه استفاده از این هدف برای گرفتن عکس، ازجمله نحوه ایجاد Uri مناسب برای مکان برونداد، گرفتن عکس یا گرفتن ویدیو را بخوانید.

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.IMAGE_CAPTURE" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

هنگام رسیدگی به این هدف، فعالیتتان EXTRA_OUTPUT اضافی را در Intent ورودی بررسی کند، سپس تصویر یا ویدیو ضبط‌شده را در مکان مشخص‌شده توسط آن اضافی ذخیره کند و setResult() را با Intent که شامل ریزعکس فشرده‌شده در اضافی به‌نام "data" است فراخوانی کند.

برنامه دوربین را در حالت تصویر ثابت شروع کنید

کنش‌های گفتاری Google

• «عکس بگیر»

برای باز کردن برنامه دوربین در حالت تصویر ثابت، از کنش INTENT_ACTION_STILL_IMAGE_CAMERA استفاده کنید.

کنش

INTENT_ACTION_STILL_IMAGE_CAMERA

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

هیچ‌کدام

Extras

هیچ‌کدام

هدف نمونه:

private fun dispatchTakePictureIntent() {
    val takePictureIntent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
    try {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE)
    } catch (e: ActivityNotFoundException) {
        // Display error state to the user.
    }
}

public void capturePhoto(String targetFilename) {
    Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE);
    intent.putExtra(MediaStore.EXTRA_OUTPUT,
            Uri.withAppendedPath(locationForPhotos, targetFilename));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.STILL_IMAGE_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

برنامه دوربین را در حالت ویدیو شروع کنید

کنش‌های گفتاری Google

• «ضبط ویدیو»

برای باز کردن برنامه دوربین در حالت ویدیو، از کنش INTENT_ACTION_VIDEO_CAMERA استفاده کنید.

کنش

INTENT_ACTION_VIDEO_CAMERA

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

هیچ‌کدام

Extras

هیچ‌کدام

هدف نمونه:

fun capturePhoto() {
    val intent = Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA)
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE)
    }
}

public void capturePhoto() {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_VIDEO_CAMERA);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.VIDEO_CAMERA" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

برنامه مخاطبین/افراد

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

انتخاب مخاطب

برای اینکه کاربر مخاطبی را انتخاب کند و به برنامه شما اجازه دهد به همه اطلاعات تماس دسترسی داشته باشد، از کنش ACTION_PICK استفاده کنید و نوع MIME را روی Contacts.CONTENT_TYPE تنظیم کنید.

نتیجه Intent که به onActivityResult() تماس برگشتی شما ارسال شده است حاوی نشانی وب content: است که به مخاطب انتخاب‌شده اشاره می‌کند. پاسخ به برنامه شما اجازه می‌دهد به‌طور موقت بااستفاده از میانای برنامه‌سازی کاربردی ارائه‌دهنده مخاطبین آن مخاطب را بخواند، حتی اگر برنامه شما اجازه READ_CONTACTS را نداشته باشد.

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

کنش

ACTION_PICK

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

Contacts.CONTENT_TYPE

هدف نمونه:

const val REQUEST_SELECT_CONTACT = 1

fun selectContact() {
    val intent = Intent(Intent.ACTION_PICK).apply {
        type = ContactsContract.Contacts.CONTENT_TYPE
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        val contactUri: Uri = data.data
        // Do something with the selected contact at contactUri.
        //...
    }
}

static final int REQUEST_SELECT_CONTACT = 1;

public void selectContact() {
    Intent intent = new Intent(Intent.ACTION_PICK);
    intent.setType(ContactsContract.Contacts.CONTENT_TYPE);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_SELECT_CONTACT);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_SELECT_CONTACT && resultCode == RESULT_OK) {
        Uri contactUri = data.getData();
        // Do something with the selected contact at contactUri.
        ...
    }
}

برای کسب اطلاعات درباره نحوه بازیابی جزئیات تماس پس‌از داشتن نشانی وب تماس، بازیابی جزئیات برای مخاطب را بخوانید.

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

انتخاب داده‌های مخاطب خاص

برای اینکه کاربر اطلاعات خاصی را از مخاطب انتخاب کند، مثلاً شماره تلفن، نشانی ایمیل، یا نوع داده دیگر، از کنش ACTION_PICK استفاده کنید و نوع MIME را به یکی از انواع محتوای زیر، مثلاً CommonDataKinds.Phone.CONTENT_TYPE برای دریافت شماره تلفن مخاطب، مشخص کنید.

توجه: در بسیاری از موارد، برنامه شما باید READ_CONTACTS اجازه مشاهده اطلاعات خاص درباره مخاطب موردنظر را داشته باشد.

اگر فقط یک نوع داده را از مخاطب بازیابی می‌کنید، این تکنیک با CONTENT_TYPE از ContactsContract.CommonDataKinds کلاس کارآمدتر از استفاده از Contacts.CONTENT_TYPE است، همان‌طور که در بخش قبلی نشان داده شد. این نتیجه بدون نیاز به اجرای پُرسمان پیچیده‌تر در ارائه‌دهنده مخاطبین، دسترسی مستقیم به داده‌های موردنظرتان را برایتان فراهم می‌کند.

نتیجه Intent که به onActivityResult() تماس برگشتی شما ارسال شد حاوی content: نشانی وب اشاره‌کننده به داده‌های مخاطب انتخاب‌شده است. پاسخ به برنامه شما اجازه‌های موقت می‌دهد تا داده‌های مخاطب را بخواند، حتی اگر برنامه شما اجازه READ_CONTACTS را نداشته باشد.

کنش

ACTION_PICK

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

CommonDataKinds.Phone.CONTENT_TYPE

از میان مخاطبین دارای شماره تلفن انتخاب کنید.

CommonDataKinds.Email.CONTENT_TYPE

از بین مخاطبین دارای نشانی ایمیل انتخاب کنید.

CommonDataKinds.StructuredPostal.CONTENT_TYPE

از میان مخاطبین دارای نشانی پستی انتخاب کنید.

یا یکی از مقادیر CONTENT_TYPE دیگر در ContactsContract.

هدف نمونه:

const val REQUEST_SELECT_PHONE_NUMBER = 1

fun selectContact() {
    // Start an activity for the user to pick a phone number from contacts.
    val intent = Intent(Intent.ACTION_PICK).apply {
        type = CommonDataKinds.Phone.CONTENT_TYPE
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == Activity.RESULT_OK) {
        // Get the URI and query the content provider for the phone number.
        val contactUri: Uri = data.data
        val projection: Array<String> = arrayOf(CommonDataKinds.Phone.NUMBER)
        contentResolver.query(contactUri, projection, null, null, null).use { cursor ->
            // If the cursor returned is valid, get the phone number.
            if (cursor.moveToFirst()) {
                val numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER)
                val number = cursor.getString(numberIndex)
                // Do something with the phone number.
                ...
            }
        }
    }
}

static final int REQUEST_SELECT_PHONE_NUMBER = 1;

public void selectContact() {
    // Start an activity for the user to pick a phone number from contacts.
    Intent intent = new Intent(Intent.ACTION_PICK);
    intent.setType(CommonDataKinds.Phone.CONTENT_TYPE);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_SELECT_PHONE_NUMBER);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_SELECT_PHONE_NUMBER && resultCode == RESULT_OK) {
        // Get the URI and query the content provider for the phone number.
        Uri contactUri = data.getData();
        String[] projection = new String[]{CommonDataKinds.Phone.NUMBER};
        Cursor cursor = getContentResolver().query(contactUri, projection,
                null, null, null);
        // If the cursor returned is valid, get the phone number.
        if (cursor != null && cursor.moveToFirst()) {
            int numberIndex = cursor.getColumnIndex(CommonDataKinds.Phone.NUMBER);
            String number = cursor.getString(numberIndex);
            // Do something with the phone number.
            //...
        }
    }
}

مشاهده مخاطب

برای نمایش جزئیات مخاطب شناخته‌شده، از کنش ACTION_VIEW استفاده کنید و مخاطب را با نشانی وب content: به‌عنوان داده هدف مشخص کنید.

دو روش اصلی برای بازیابی اولیه نشانی وب مخاطب وجود دارد:

• از نشانی وب مخاطب برگشت‌داده‌شده توسط کنش ACTION_PICK نشان‌داده‌شده در بخش قبلی استفاده کنید. این رویکرد به هیچ اجازه برنامه‌ای نیاز ندارد.
• دسترسی مستقیم به فهرست همه مخاطبین، همان‌طور که در واکشی فهرست مخاطبین توضیح داده شده است. این رویکرد به اجازه READ_CONTACTS نیاز دارد.

کنش

ACTION_VIEW

طرح‌واره URI داده

content:<URI>

نوع MIME

هیچ‌کدام. نوع از نشانی وب مخاطب استنباط می‌شود.

هدف نمونه:

fun viewContact(contactUri: Uri) {
    val intent = Intent(Intent.ACTION_VIEW, contactUri)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void viewContact(Uri contactUri) {
    Intent intent = new Intent(Intent.ACTION_VIEW, contactUri);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

ویرایش مخاطب موجود

برای ویرایش مخاطب شناخته‌شده، از کنش ACTION_EDIT استفاده کنید، مخاطب را با content: نشانی وب به‌عنوان داده هدف مشخص کنید، و هرگونه اطلاعات مخاطب شناخته‌شده را در موارد اضافی مشخص‌شده توسط ثابت‌ها در ContactsContract.Intents.Insert اضافه کنید.

دو روش اصلی برای بازیابی اولیه نشانی وب مخاطب وجود دارد:

• از نشانی وب مخاطب برگشت‌داده‌شده توسط کنش ACTION_PICK نشان‌داده‌شده در بخش قبلی استفاده کنید. این رویکرد به هیچ اجازه برنامه‌ای نیاز ندارد.
• دسترسی مستقیم به فهرست همه مخاطبین، همان‌طور که در واکشی فهرست مخاطبین توضیح داده شده است. این رویکرد به اجازه READ_CONTACTS نیاز دارد.

کنش

ACTION_EDIT

طرح‌واره URI داده

content:<URI>

نوع MIME

نوع از نشانی وب مخاطب استنباط می‌شود.

Extras

یک یا چند مورد از موارد اضافی تعریف‌شده در ContactsContract.Intents.Insert تا بتوانید فیلدهای جزئیات تماس را تکمیل کنید.

هدف نمونه:

fun editContact(contactUri: Uri, email: String) {
    val intent = Intent(Intent.ACTION_EDIT).apply {
        data = contactUri
        putExtra(ContactsContract.Intents.Insert.EMAIL, email)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void editContact(Uri contactUri, String email) {
    Intent intent = new Intent(Intent.ACTION_EDIT);
    intent.setData(contactUri);
    intent.putExtra(Intents.Insert.EMAIL, email);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

برای کسب اطلاعات بیشتر درباره نحوه ویرایش مخاطب، اصلاح مخاطبین بااستفاده از هدف‌ها را بخوانید.

درج مخاطب

برای درج مخاطب جدید، از کنش ACTION_INSERT استفاده کنید، نوع MIME را Contacts.CONTENT_TYPE مشخص کنید، و هرگونه اطلاعات تماس شناخته‌شده را در موارد اضافی مشخص‌شده توسط ثابت‌ها در ContactsContract.Intents.Insert اضافه کنید.

کنش

ACTION_INSERT

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

Contacts.CONTENT_TYPE

Extras

یک یا چند مورد اضافی تعریف‌شده در ContactsContract.Intents.Insert.

هدف نمونه:

fun insertContact(name: String, email: String) {
    val intent = Intent(Intent.ACTION_INSERT).apply {
        type = ContactsContract.Contacts.CONTENT_TYPE
        putExtra(ContactsContract.Intents.Insert.NAME, name)
        putExtra(ContactsContract.Intents.Insert.EMAIL, email)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void insertContact(String name, String email) {
    Intent intent = new Intent(Intent.ACTION_INSERT);
    intent.setType(Contacts.CONTENT_TYPE);
    intent.putExtra(Intents.Insert.NAME, name);
    intent.putExtra(Intents.Insert.EMAIL, email);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

برای کسب اطلاعات بیشتر درباره نحوه درج مخاطب، اصلاح مخاطبان بااستفاده از هدف‌ها را بخوانید.

ایمیل

نوشتن ایمیل با پیوست‌های اختیاری کنشی رایج برای برنامه‌های ایمیل است. بااستفاده از اطلاعات بخش زیر، فیلتر هدفی ایجاد کنید تا توانایی برنامه‌تان را برای انجام این کنش تبلیغ کنید.

ایمیلی با پیوست‌های اختیاری بنویس

برای نوشتن ایمیل، براساس اینکه پیوست اضافه می‌کنید یا نه، از یکی از کنش‌های زیر استفاده کنید، و جزئیات ایمیل مثل گیرنده و موضوع را بااستفاده از کلیدهای اضافی فهرست‌شده اضافه کنید.

کنش

ACTION_SENDTO (برای بدون پیوست) یا
ACTION_SEND (برای یک پیوست) یا
ACTION_SEND_MULTIPLE (برای چند پیوست)

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

"text/plain"

"*/*"

Extras

Intent.EXTRA_EMAIL

آرایه رشته‌ای از همه نشانی‌های ایمیل گیرندگان «به».

Intent.EXTRA_CC

آرایه رشته‌ای از همه نشانی‌های ایمیل گیرندگان «رونوشت».

Intent.EXTRA_BCC

آرایه رشته‌ای از همه نشانی‌های ایمیل گیرندگان «رونوشت مخفی».

Intent.EXTRA_SUBJECT

رشته‌ای با موضوع ایمیل.

Intent.EXTRA_TEXT

رشته‌ای با متن ایمیل.

Intent.EXTRA_STREAM

‫Uri که به پیوست اشاره می‌کند. اگر از کنش ACTION_SEND_MULTIPLE استفاده می‌کنید، این به‌جای آن ArrayList حاوی چندین شیء Uri است.

هدف نمونه:

fun composeEmail(addresses: Array<String>, subject: String, attachment: Uri) {
    val intent = Intent(Intent.ACTION_SEND).apply {
        type = "*/*"
        putExtra(Intent.EXTRA_EMAIL, addresses)
        putExtra(Intent.EXTRA_SUBJECT, subject)
        putExtra(Intent.EXTRA_STREAM, attachment)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void composeEmail(String[] addresses, String subject, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setType("*/*");
    intent.putExtra(Intent.EXTRA_EMAIL, addresses);
    intent.putExtra(Intent.EXTRA_SUBJECT, subject);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

اگر می‌خواهید مطمئن شوید که هدف شما فقط توسط برنامه ایمیل مدیریت می‌شود و نه برنامه پیامک یا اجتماعی، از کنش ACTION_SENDTO استفاده کنید و طرح داده "mailto:" را همان‌طور که در مثال زیر نشان داده شده است اضافه کنید:

fun composeEmail(addresses: Array<String>, subject: String) {
    val intent = Intent(Intent.ACTION_SENDTO).apply {
        data = Uri.parse("mailto:") // Only email apps handle this.
        putExtra(Intent.EXTRA_EMAIL, addresses)
        putExtra(Intent.EXTRA_SUBJECT, subject)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void composeEmail(String[] addresses, String subject) {
    Intent intent = new Intent(Intent.ACTION_SENDTO);
    intent.setData(Uri.parse("mailto:")); // Only email apps handle this.
    intent.putExtra(Intent.EXTRA_EMAIL, addresses);
    intent.putExtra(Intent.EXTRA_SUBJECT, subject);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="*/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.SENDTO" />
        <data android:scheme="mailto" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

فضای ذخیره‌سازی فایل

در زیر کنش‌های رایج برای برنامه‌های ذخیره‌سازی فایل، ازجمله اطلاعاتی که برای ایجاد فیلتر هدف برای تبلیغ توانایی برنامه در انجام هر کنش نیاز دارید، آورده شده است.

بازیابی نوع خاصی از فایل

برای درخواست از کاربر برای انتخاب فایلی مثل سند یا عکس و برگرداندن مرجع به برنامه شما، از کنش ACTION_GET_CONTENT استفاده کنید و نوع MIME موردنظرتان را مشخص کنید. مرجع فایل برگشتی به برنامه شما برای چرخه حیات فعلی فعالیت شما گذرا است، بنابراین اگر می‌خواهید بعداً به آن دسترسی داشته باشید باید نسخه‌ای را وارد کنید که بتوانید بعداً آن را بخوانید.

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

هدف نتیجه‌ای که به روش onActivityResult() شما ارائه می‌شود شامل داده‌هایی با نشانی وب اشاره‌کننده به فایل است. نشانی وب می‌تواند هر چیزی باشد، مثلاً نشانی وب http:، نشانی وب file:، یا نشانی وب content: URI. بااین‌حال، اگر می‌خواهید فایل‌های قابل‌انتخاب را به فایل‌هایی که فقط از ارائه‌دهنده محتوا (content: نشانی وب) دردسترس هستند و به‌عنوان جاری‌سازی فایل با openFileDescriptor() دردسترس هستند محدود کنید، دسته CATEGORY_OPENABLE را به هدف خود اضافه کنید.

در Android 4.3 (سطح میانای برنامه کاربردی ۱۸) و بالاتر، با افزودن EXTRA_ALLOW_MULTIPLE به هدف، که روی true تنظیم شده است، می‌توانید به کاربر اجازه دهید چندین فایل را انتخاب کند. سپس می‌توانید به هریک از فایل‌های انتخاب‌شده در ClipData شیء برگشتی از getClipData() دسترسی داشته باشید.

کنش

ACTION_GET_CONTENT

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

نوع MIME مربوط به نوع فایلی که کاربر باید انتخاب کند.

Extras

EXTRA_ALLOW_MULTIPLE

مقدار بولی که اعلام می‌کند آیا کاربر می‌تواند بیش‌از یک فایل را به‌طور هم‌زمان انتخاب کند یا نه.

EXTRA_LOCAL_ONLY

بولی که اعلام می‌کند آیا فایل برگشتی باید مستقیماً از دستگاه دردسترس باشد یا اینکه باید از سرویس راه دور بارگیری شود.

دسته (اختیاری)

CATEGORY_OPENABLE

برای برگرداندن فقط فایل‌های «بازشدنی» که می‌توانند به‌عنوان جاری‌سازی فایل نشان داده شوند با openFileDescriptor().

مثال هدف برای دریافت عکس:

const val REQUEST_IMAGE_GET = 1

fun selectImage() {
    val intent = Intent(Intent.ACTION_GET_CONTENT).apply {
        type = "image/*"
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == Activity.RESULT_OK) {
        val thumbnail: Bitmap = data.getParcelableExtra("data")
        val fullPhotoUri: Uri = data.data
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

static final int REQUEST_IMAGE_GET = 1;

public void selectImage() {
    Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
    intent.setType("image/*");
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_GET);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_GET && resultCode == RESULT_OK) {
        Bitmap thumbnail = data.getParcelable("data");
        Uri fullPhotoUri = data.getData();
        // Do work with photo saved at fullPhotoUri.
        ...
    }
}

فیلتر هدف نمونه برای برگرداندن عکس:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.GET_CONTENT" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- The OPENABLE category declares that the returned file is accessible
             from a content provider that supports OpenableColumns
             and ContentResolver.openFileDescriptor(). -->
        <category android:name="android.intent.category.OPENABLE" />
    </intent-filter>
</activity>

باز کردن نوع خاصی از فایل

به‌جای بازیابی نسخه کپی از فایلی که باید به برنامه‌تان وارد کنید، بااستفاده از کنش ACTION_GET_CONTENT، وقتی در Android نسخه ۴.۴ یا بالاتر اجرا می‌کنید، می‌توانید به‌جای آن درخواست کنید فایلی که توسط برنامه دیگری مدیریت می‌شود بااستفاده از کنش ACTION_OPEN_DOCUMENT و مشخص کردن نوع MIME باز شود. برای اینکه به کاربر اجازه دهید سند جدیدی ایجاد کند که برنامه‌تان بتواند در آن بنویسد، به‌جای آن از کنش ACTION_CREATE_DOCUMENT استفاده کنید.

برای مثال، به‌جای انتخاب از میان اسناد PDF موجود، هدف ACTION_CREATE_DOCUMENT به کاربران امکان می‌دهد انتخاب کنند که می‌خواهند سند جدید را کجا ایجاد کنند، مثلاً در برنامه دیگری که فضای ذخیره‌سازی سند را مدیریت می‌کند. برنامه شما سپس مکان نشانی وب (URI) را که در آن می‌تواند سند جدید را بنویسد دریافت می‌کند.

درحالی‌که هدف تحویل‌شده به روش onActivityResult() از کنش ACTION_GET_CONTENT ممکن است نشانی وب از هر نوعی را برگرداند، هدف نتیجه از ACTION_OPEN_DOCUMENT و ACTION_CREATE_DOCUMENT همیشه فایل انتخاب‌شده را به‌عنوان نشانی وب content: که با DocumentsProvider پشتیبانی می‌شود مشخص می‌کند. می‌توانید فایل را با openFileDescriptor() باز کنید و جزئیات آن را بااستفاده از ستون‌های DocumentsContract.Document پُرسمان کنید.

‫URI برگشتی به برنامه شما دسترسی خواندن بلندمدت به فایل می‌دهد، و احتمالاً دسترسی نوشتن نیز می‌دهد. کنش ACTION_OPEN_DOCUMENT به‌ویژه زمانی مفید است که بخواهید فایل موجودی را بدون اینکه نسخه‌ای از آن در برنامه‌تان ایجاد کنید بخوانید یا زمانی که بخواهید فایلی را در همان مکان باز و ویرایش کنید.

همچنین می‌توانید با افزودن EXTRA_ALLOW_MULTIPLE به هدف و تنظیم آن روی true، به کاربر اجازه دهید چندین فایل را انتخاب کند. اگر کاربر فقط یک مورد را انتخاب کند، می‌توانید آن مورد را از getData() بازیابی کنید. اگر کاربر بیش‌از یک مورد را انتخاب کند، getData() مقدار null برمی‌گرداند و درعوض باید هر مورد را از شیء ClipData که توسط getClipData() برگردانده می‌شود بازیابی کنید.

توجه: هدف شما باید نوع MIME را مشخص کند و باید دسته CATEGORY_OPENABLE را اعلام کند. درصورت لزوم، می‌توانید با افزودن آرایه‌ای از انواع MIME با EXTRA_MIME_TYPES اضافی، بیش‌از یک نوع MIME مشخص کنید—اگر این کار را انجام دهید، باید نوع MIME اصلی را در setType() به "*/*" تنظیم کنید.

کنش

ACTION_OPEN_DOCUMENT یا
ACTION_CREATE_DOCUMENT

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

نوع MIME مربوط به نوع فایلی که کاربر باید انتخاب کند.

Extras

EXTRA_MIME_TYPES

آرایه‌ای از انواع MIME مربوط به انواع فایل‌هایی که برنامه شما درخواست می‌کند. وقتی از این افزونه استفاده می‌کنید، باید نوع MIME اصلی را در setType() روی "*/*" تنظیم کنید.

EXTRA_ALLOW_MULTIPLE

مقدار بولی که اعلام می‌کند آیا کاربر می‌تواند بیش‌از یک فایل را به‌طور هم‌زمان انتخاب کند یا نه.

EXTRA_TITLE

برای استفاده با ACTION_CREATE_DOCUMENT برای مشخص کردن نام فایل اولیه.

EXTRA_LOCAL_ONLY

بولی که اعلام می‌کند آیا فایل برگشتی باید مستقیماً از دستگاه دردسترس باشد یا اینکه باید از سرویس راه دور بارگیری شود.

دسته

CATEGORY_OPENABLE

برای برگرداندن فقط فایل‌های «بازشدنی» که می‌توانند به‌عنوان جاری‌سازی فایل نشان داده شوند با openFileDescriptor().

مثال هدف برای دریافت عکس:

const val REQUEST_IMAGE_OPEN = 1

fun selectImage2() {
    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
        type = "image/*"
        addCategory(Intent.CATEGORY_OPENABLE)
    }
    // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test.
    startActivityForResult(intent, REQUEST_IMAGE_OPEN)
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_OPEN && resultCode == Activity.RESULT_OK) {
        val fullPhotoUri: Uri = data.data
        // Do work with full size photo saved at fullPhotoUri.
        ...
    }
}

static final int REQUEST_IMAGE_OPEN = 1;

public void selectImage() {
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
    intent.setType("image/*");
    intent.addCategory(Intent.CATEGORY_OPENABLE);
    // Only the system receives the ACTION_OPEN_DOCUMENT, so no need to test.
    startActivityForResult(intent, REQUEST_IMAGE_OPEN);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_OPEN && resultCode == RESULT_OK) {
        Uri fullPhotoUri = data.getData();
        // Do work with full size photo saved at fullPhotoUri.
        ...
    }
}

برنامه‌های طرف سوم نمی‌توانند به هدف با کنش ACTION_OPEN_DOCUMENT پاسخ دهند. درعوض، سیستم این هدف را دریافت می‌کند و همه فایل‌های دردسترس از برنامه‌های مختلف را در یک واسط کاربر یکپارچه نمایش می‌دهد.

برای ارائه فایل‌های برنامه در این رابط کاربری و اجازه دادن به برنامه‌های دیگر برای باز کردن آن‌ها، باید DocumentsProvider را پیاده‌سازی کنید و فیلتر قصدی برای PROVIDER_INTERFACE ("android.content.action.DOCUMENTS_PROVIDER") اضافه کنید، همان‌طور که در مثال زیر نشان داده شده است:

<provider ...
    android:grantUriPermissions="true"
    android:exported="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
</provider>

برای کسب اطلاعات بیشتر درباره اینکه چگونه فایل‌های مدیریت‌شده توسط برنامه‌تان را از برنامه‌های دیگر باز کنید، باز کردن فایل‌ها بااستفاده از چارچوب دسترسی به فضای ذخیره‌سازی را بخوانید.

کنش‌های محلی

درخواست خودرو یک کنش محلی رایج است. بااستفاده از اطلاعات بخش زیر، فیلتر هدفی ایجاد کنید تا توانایی برنامه‌تان را برای انجام این کنش تبلیغ کنید.

درخواست تاکسی تلفنی

کنش‌های گفتاری Google

• «تاکسی بگیر»
• «ماشین خبر کن»

(فقط Wear OS)

برای تماس با تاکسی، از ACTION_RESERVE_TAXI_RESERVATION کنش استفاده کنید.

توجه: برنامه‌ها باید قبل‌از تکمیل این کنش، از کاربر تأییدیه بخواهند.

کنش

ACTION_RESERVE_TAXI_RESERVATION

نشانی وب داده

هیچ‌کدام

نوع MIME

هیچ‌کدام

Extras

هیچ‌کدام

هدف نمونه:

fun callCar() {
    val intent = Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void callCar() {
    Intent intent = new Intent(ReserveIntents.ACTION_RESERVE_TAXI_RESERVATION);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="com.google.android.gms.actions.RESERVE_TAXI_RESERVATION" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Maps

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

نمایش مکان روی نقشه

برای باز کردن نقشه، از کنش ACTION_VIEW استفاده کنید و اطلاعات مکان را در داده‌های هدف با یکی از طرح‌های زیر مشخص کنید.

کنش

ACTION_VIEW

طرح‌واره URI داده

geo:latitude,longitude

نقشه را در طول و عرض جغرافیایی داده‌شده نشان بده.

مثال: "geo:47.6,-122.3"

geo:latitude,longitude?z=zoom

نقشه را در طول و عرض جغرافیایی داده‌شده در سطح بزرگ‌نمایی معینی نشان می‌دهد. سطح بزرگ‌نمایی ۱ کل زمین را نشان می‌دهد که در lat،lng داده‌شده مرکزیت دارد. بالاترین (نزدیک‌ترین) سطح بزرگ‌نمایی ۲۳ است.

مثال: "geo:47.6,-122.3?z=11"

geo:0,0?q=lat,lng(label)

نقشه را در طول و عرض جغرافیایی داده‌شده با برچسب رشته‌ای نشان می‌دهد.

مثال: "geo:0,0?q=34.99,-106.61(Treasure)"

geo:0,0?q=my+street+address

مکان «نشانی خیابان من» را نشان بده، که می‌تواند نشانی خاص یا پُرسمان مکان باشد.

مثال: "geo:0,0?q=1600+Amphitheatre+Parkway%2C+CA"

توجه: همه رشته‌های منتقل‌شده در نشانی وب geo باید کدبندی شوند. برای مثال، رشته 1st & Pike, Seattle به 1st%20%26%20Pike%2C%20Seattle تبدیل می‌شود. فاصله‌های موجود در رشته با %20 کدبندی می‌شوند یا با علامت به‌علاوه (+) جایگزین می‌شوند.

نوع MIME

هیچ‌کدام

هدف نمونه:

fun showMap(geoLocation: Uri) {
    val intent = Intent(Intent.ACTION_VIEW).apply {
        data = geoLocation
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void showMap(Uri geoLocation) {
    Intent intent = new Intent(Intent.ACTION_VIEW);
    intent.setData(geoLocation);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="geo" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

موسیقی یا ویدیو

در زیر، کنش‌های رایج برای برنامه‌های موسیقی و ویدیو، ازجمله اطلاعاتی که برای ایجاد فیلتر هدف به‌منظور تبلیغ توانایی برنامه برای انجام هر کنش نیاز دارید، آورده شده است.

پخش فایل رسانه‌ای

برای پخش فایل موسیقی، از کنش ACTION_VIEW استفاده کنید و مکان نشانی وب فایل را در داده‌های هدف مشخص کنید.

کنش

ACTION_VIEW

طرح‌واره URI داده

file:<URI>

content:<URI>

http:<URL>

نوع MIME

"audio/*"

"application/ogg"

"application/x-ogg"

"application/itunes"

یا هر چیز دیگری که برنامه شما نیاز دارد.

هدف نمونه:

fun playMedia(file: Uri) {
    val intent = Intent(Intent.ACTION_VIEW).apply {
        data = file
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void playMedia(Uri file) {
    Intent intent = new Intent(Intent.ACTION_VIEW);
    intent.setData(file);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <data android:type="audio/*" />
        <data android:type="application/ogg" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

پخش موسیقی براساس پُرسمان جستجو

کنش‌های گفتاری Google

• «play michael jackson billie jean» (پخش مایکل جکسون بیلی جین)

برای پخش موسیقی براساس پُرسمان جستجو، از هدف INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH استفاده کنید. برنامه ممکن است این هدف را در پاسخ به فرمان صوتی کاربر برای پخش موسیقی راه‌اندازی کند. برنامه دریافت‌کننده برای این هدف، جستجویی در فهرست موجودی خود انجام می‌دهد تا محتوای موجود را با پُرسمان داده‌شده مطابقت دهد و پخش آن محتوا را شروع کند.

در این هدف، رشته EXTRA_MEDIA_FOCUS اضافی را که حالت جستجوی موردنظر را مشخص می‌کند اضافه کنید. برای مثال، حالت جستجو می‌تواند مشخص کند که جستجو برای نام هنرمند است یا نام آهنگ.

کنش

INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

هیچ‌کدام

Extras

MediaStore.EXTRA_MEDIA_FOCUS (الزامی)

حالت جستجو را نشان می‌دهد: اینکه کاربر به‌دنبال هنرمند، آلبوم، آهنگ، یا فهرست پخش خاصی است یا نه. بیشتر حالت‌های جستجو به لوازم جانبی اضافی نیاز دارند. برای مثال، اگر کاربر به گوش دادن به آهنگ خاصی علاقه‌مند باشد، ممکن است هدف سه مورد اضافی داشته باشد: عنوان آهنگ، هنرمند، و آلبوم. این هدف از حالت‌های جستجوی زیر برای هر مقدار EXTRA_MEDIA_FOCUS پشتیبانی می‌کند:

همه - "vnd.android.cursor.item/*"

هر نوع موسیقی پخش شود. برنامه دریافت‌کننده براساس یک انتخاب هوشمند، مانند آخرین فهرست پخشی که کاربر گوش داده است، موسیقی پخش می‌کند.

اضافه‌های دیگر:

• ‫QUERY (الزامی): رشته‌ای خالی. این مورد اضافی همیشه برای سازگاری با نسخه قدیمی ارائه می‌شود. برنامه‌های موجود که از حالت‌های جستجو اطلاعی ندارند می‌توانند این هدف را به‌عنوان جستجوی بدون ساختار پردازش کنند.

بدون ساختار - "vnd.android.cursor.item/*"

آهنگ، آلبوم، یا ژانر خاصی را از پُرسمان جستجوی بدون ساختار پخش کنید. برنامه‌ها می‌توانند وقتی نمی‌توانند نوع محتوایی را که کاربر می‌خواهد گوش دهد شناسایی کنند، با این حالت جستجو هدف تولید کنند. درصورت امکان، از حالت‌های جستجوی دقیق‌تر استفاده کنید.

امکانات اضافه دیگر:

• ‫QUERY (الزامی): رشته‌ای که شامل هر ترکیبی از هنرمند، آلبوم، نام آهنگ، یا ژانر باشد.

ژانر - Audio.Genres.ENTRY_CONTENT_TYPE

موسیقی از ژانر خاصی پخش کن.

اضافه‌های دیگر:

• ‫"android.intent.extra.genre" (الزامی) - ژانر.
• ‫QUERY (الزامی): ژانر. این مورد اضافی همیشه برای سازگاری با نسخه قدیمی ارائه می‌شود. برنامه‌های موجود که با حالت‌های جستجو آشنا نیستند می‌توانند این هدف را به‌عنوان جستجوی بدون ساختار پردازش کنند.

هنرمند - Audio.Artists.ENTRY_CONTENT_TYPE

پخش موسیقی از هنرمندی خاص.

اضافه‌های دیگر:

• ‫EXTRA_MEDIA_ARTIST (الزامی): هنرمند.
• ‫"android.intent.extra.genre": ژانر.
• ‫QUERY (الزامی): رشته‌ای که شامل هر ترکیبی از هنرمند یا ژانر باشد. این مورد اضافی همیشه برای سازگاری با نسخه قدیمی ارائه می‌شود. برنامه‌های موجود که از حالت‌های جستجو اطلاعی ندارند می‌توانند این هدف را به‌عنوان جستجوی غیرساختاری پردازش کنند.

آلبوم - Audio.Albums.ENTRY_CONTENT_TYPE

موسیقی از آلبومی خاص پخش کن.

اضافه‌های دیگر:

• ‫EXTRA_MEDIA_ALBUM (الزامی): آلبوم.
• ‫EXTRA_MEDIA_ARTIST: هنرمند.
• ‫"android.intent.extra.genre": ژانر.
• ‫QUERY (الزامی): رشته‌ای که شامل هر ترکیبی از آلبوم یا هنرمند است. این مورد اضافی همیشه برای سازگاری با نسخه قدیمی ارائه می‌شود. برنامه‌های موجود که با حالت‌های جستجو آشنا نیستند می‌توانند این هدف را به‌عنوان جستجوی بدون ساختار پردازش کنند.

آهنگ - "vnd.android.cursor.item/audio"

آهنگ خاصی را پخش کنید.

اضافه‌های دیگر:

• ‫EXTRA_MEDIA_ALBUM: آلبوم.
• ‫EXTRA_MEDIA_ARTIST: هنرمند.
• ‫"android.intent.extra.genre": ژانر.
• ‫EXTRA_MEDIA_TITLE (الزامی): نام آهنگ.
• ‫QUERY (الزامی): رشته‌ای که شامل هر ترکیبی از آلبوم، هنرمند، ژانر، یا عنوان باشد. این مورد اضافی همیشه برای سازگاری با نسخه قدیمی ارائه می‌شود. برنامه‌های موجود که از حالت‌های جستجو اطلاعی ندارند می‌توانند این هدف را به‌عنوان جستجوی بدون ساختار پردازش کنند.

فهرست پخش - Audio.Playlists.ENTRY_CONTENT_TYPE

فهرست پخش خاصی یا فهرست پخشی را که با معیارهای مشخص‌شده در افزونه‌های اضافی مطابقت دارد پخش کنید.

امکانات اضافه دیگر:

• ‫EXTRA_MEDIA_ALBUM: آلبوم.
• ‫EXTRA_MEDIA_ARTIST: هنرمند.
• ‫"android.intent.extra.genre": ژانر.
• ‫"android.intent.extra.playlist": فهرست پخش.
• ‫EXTRA_MEDIA_TITLE: نام آهنگی که فهرست پخش براساس آن ساخته شده است.
• ‫QUERY (الزامی): رشته‌ای که شامل هر ترکیبی از آلبوم، هنرمند، ژانر، فهرست پخش، یا عنوان باشد. این مورد اضافی همیشه برای سازگاری با نسخه قدیمی ارائه می‌شود. برنامه‌های موجود که از حالت‌های جستجو اطلاعی ندارند می‌توانند این هدف را به‌عنوان جستجوی بدون ساختار پردازش کنند.

هدف نمونه:

اگر کاربر بخواهد به موسیقی هنرمند خاصی گوش دهد، برنامه جستجو ممکن است قصد زیر را تولید کند:

fun playSearchArtist(artist: String) {
    val intent = Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH).apply {
        putExtra(MediaStore.EXTRA_MEDIA_FOCUS, MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE)
        putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist)
        putExtra(SearchManager.QUERY, artist)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

public void playSearchArtist(String artist) {
    Intent intent = new Intent(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH);
    intent.putExtra(MediaStore.EXTRA_MEDIA_FOCUS,
                    MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE);
    intent.putExtra(MediaStore.EXTRA_MEDIA_ARTIST, artist);
    intent.putExtra(SearchManager.QUERY, artist);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.media.action.MEDIA_PLAY_FROM_SEARCH" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

هنگام مدیریت این هدف در فعالیتتان، مقدار EXTRA_MEDIA_FOCUS اضافی در ورودی Intent را بررسی کنید تا حالت جستجو را تعیین کنید. پس‌از اینکه فعالیت شما حالت جستجو را شناسایی کرد، مقادیر لوازم جانبی اضافی را برای آن حالت جستجوی خاص بخوانید. با این اطلاعات، برنامه شما می‌تواند جستجو را در موجودی خود انجام دهد تا محتوایی را که با پُرسمان جستجو مطابقت دارد پخش کند. این مورد در مثال زیر نشان داده شده است.

override fun onCreate(savedInstanceState: Bundle?) {
    ...
    if (intent.action.compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) {

        val mediaFocus: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS)
        val query: String? = intent.getStringExtra(SearchManager.QUERY)

        // Some of these extras might not be available depending on the search mode.
        val album: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM)
        val artist: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST)
        val genre: String? = intent.getStringExtra("android.intent.extra.genre")
        val playlist: String? = intent.getStringExtra("android.intent.extra.playlist")
        val title: String? = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE)

        // Determine the search mode and use the corresponding extras.
        when {
            mediaFocus == null -> {
                // 'Unstructured' search mode (backward compatible)
                playUnstructuredSearch(query)
            }
            mediaFocus.compareTo("vnd.android.cursor.item/*") == 0 -> {
                if (query?.isNotEmpty() == true) {
                    // 'Unstructured' search mode.
                    playUnstructuredSearch(query)
                } else {
                    // 'Any' search mode.
                    playResumeLastPlaylist()
                }
            }
            mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Genre' search mode.
                playGenre(genre)
            }
            mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Artist' search mode.
                playArtist(artist, genre)
            }
            mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Album' search mode.
                playAlbum(album, artist)
            }
            mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0 -> {
                // 'Song' search mode.
                playSong(album, artist, genre, title)
            }
            mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0 -> {
                // 'Playlist' search mode.
                playPlaylist(album, artist, genre, playlist, title)
            }
        }
    }
}

protected void onCreate(Bundle savedInstanceState) {
    //...
    Intent intent = this.getIntent();
    if (intent.getAction().compareTo(MediaStore.INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH) == 0) {

        String mediaFocus = intent.getStringExtra(MediaStore.EXTRA_MEDIA_FOCUS);
        String query = intent.getStringExtra(SearchManager.QUERY);

        // Some of these extras might not be available depending on the search mode.
        String album = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ALBUM);
        String artist = intent.getStringExtra(MediaStore.EXTRA_MEDIA_ARTIST);
        String genre = intent.getStringExtra("android.intent.extra.genre");
        String playlist = intent.getStringExtra("android.intent.extra.playlist");
        String title = intent.getStringExtra(MediaStore.EXTRA_MEDIA_TITLE);

        // Determine the search mode and use the corresponding extras.
        if (mediaFocus == null) {
            // 'Unstructured' search mode (backward compatible).
            playUnstructuredSearch(query);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/*") == 0) {
            if (query.isEmpty()) {
                // 'Any' search mode.
                playResumeLastPlaylist();
            } else {
                // 'Unstructured' search mode.
                playUnstructuredSearch(query);
            }

        } else if (mediaFocus.compareTo(MediaStore.Audio.Genres.ENTRY_CONTENT_TYPE) == 0) {
            // 'Genre' search mode.
            playGenre(genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Artists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Artist' search mode.
            playArtist(artist, genre);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Albums.ENTRY_CONTENT_TYPE) == 0) {
            // 'Album' search mode.
            playAlbum(album, artist);

        } else if (mediaFocus.compareTo("vnd.android.cursor.item/audio") == 0) {
            // 'Song' search mode.
            playSong(album, artist, genre, title);

        } else if (mediaFocus.compareTo(MediaStore.Audio.Playlists.ENTRY_CONTENT_TYPE) == 0) {
            // 'Playlist' search mode.
            playPlaylist(album, artist, genre, playlist, title);
        }
    }
}

یادداشت جدید

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

ایجاد یادداشت

برای ایجاد یادداشت جدید، از کنش ACTION_CREATE_NOTE استفاده کنید و جزئیات یادداشت مثل موضوع و نوشتار را بااستفاده از موارد اضافی زیر مشخص کنید.

توجه: برنامه‌ها باید قبل‌از تکمیل این کنش، از کاربر تأییدیه بخواهند.

کنش

ACTION_CREATE_NOTE

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

PLAIN_TEXT_TYPE

"*/*"

Extras

EXTRA_NAME

رشته‌ای که عنوان یا موضوع یادداشت را نشان می‌دهد.

EXTRA_TEXT

رشته‌ای که نوشتار یادداشت را نشان می‌دهد.

هدف نمونه:

کاتلین

fun createNote(subject: String, text: String) {
    val intent = Intent(NoteIntents.ACTION_CREATE_NOTE).apply {
        putExtra(NoteIntents.EXTRA_NAME, subject)
        putExtra(NoteIntents.EXTRA_TEXT, text)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void createNote(String subject, String text) {
    Intent intent = new Intent(NoteIntents.ACTION_CREATE_NOTE)
            .putExtra(NoteIntents.EXTRA_NAME, subject)
            .putExtra(NoteIntents.EXTRA_TEXT, text);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="com.google.android.gms.actions.CREATE_NOTE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="*/*" />
    </intent-filter>
</activity>

تلفن

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

شروع تماس تلفنی

برای باز کردن برنامه تلفن و شماره‌گیری، از کنش ACTION_DIAL استفاده کنید و شماره تلفن را بااستفاده از طرح نشانی وب زیر مشخص کنید. وقتی برنامه تلفن باز می‌شود، شماره تلفن را نمایش می‌دهد، و کاربر باید روی دکمه تماس تک‌ضرب بزند تا تماس تلفنی شروع شود.

کنش‌های گفتاری Google

• «با ۵۵۵-۵۵۵۵ تماس بگیر»
• «با باب تماس بگیر»
• «با پست صوتی تماس بگیر»

برای برقراری مستقیم تماس تلفنی، از کنش ACTION_CALL استفاده کنید و شماره تلفن را بااستفاده از طرح نشانی وب زیر مشخص کنید. وقتی برنامه تلفن باز می‌شود، تماس تلفنی شروع می‌شود. کاربر نیازی به ضربه زدن روی دکمه تماس ندارد.

کنش ACTION_CALL مستلزم این است که اجازه CALL_PHONE را به فایل مانیفست خود اضافه کنید:

<uses-permission android:name="android.permission.CALL_PHONE" />

کنش

• ACTION_DIAL - برنامه شماره‌گیر یا تلفن را باز می‌کند.
• ACTION_CALL - تماس تلفنی برقرار می‌کند (به اجازه CALL_PHONE نیاز دارد)

طرح‌واره URI داده

• tel:<phone-number>
• voicemail:<phone-number>

نوع MIME

هیچ‌کدام

شماره تلفن‌های معتبر شماره‌هایی هستند که در IETF RFC 3966 تعریف شده‌اند. نمونه‌های معتبر شامل موارد زیر می‌شود:

• tel:2125551212
• tel:(212) 555 1212

شماره‌گیر برنامه «تلفن» در عادی‌سازی طرح‌ها، مانند شماره‌های تلفن، خوب عمل می‌کند. بنابراین طرحی که شرح داده شده است در روش Uri.parse() کاملاً الزامی نیست. بااین‌حال، اگر طرحی را امتحان نکرده‌اید یا مطمئن نیستید که آیا می‌توان آن را مدیریت کرد، به‌جای آن از روش Uri.fromParts() استفاده کنید.

هدف نمونه:

کاتلین

fun dialPhoneNumber(phoneNumber: String) {
    val intent = Intent(Intent.ACTION_DIAL).apply {
        data = Uri.parse("tel:$phoneNumber")
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void dialPhoneNumber(String phoneNumber) {
    Intent intent = new Intent(Intent.ACTION_DIAL);
    intent.setData(Uri.parse("tel:" + phoneNumber));
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

جستجو

در زیر کنش‌های رایج برای برنامه‌های جستجو، ازجمله اطلاعاتی که برای ایجاد فیلتر هدف برای تبلیغ توانایی برنامه‌تان در انجام هر کنش نیاز دارید، آمده است.

جستجو بااستفاده از برنامه‌ای خاص

کنش‌های گفتاری Google

• «ویدیوهای گربه را در myvideoapp جستجو کن»

برای پشتیبانی از جستجو در بافت برنامه‌تان، فیلتر هدفی را در برنامه‌تان با کنش SEARCH_ACTION اعلام کنید، همان‌طور که در مثال فیلتر هدف زیر نشان داده شده است.

توجه: استفاده از SEARCH_ACTION برای جستجوی برنامه را توصیه نمی‌کنیم. درعوض، GET_THING کنش را پیاده‌سازی کنید تا از پشتیبانی داخلی «دستیار Google» برای جستجوی درون‌برنامه‌ای بهره ببرید. برای اطلاعات بیشتر، به اسناد کنش‌های برنامه «دستیار Google» مراجعه کنید.

کنش

"com.google.android.gms.actions.SEARCH_ACTION"

از پُرسمان‌های جستجو در «کنش‌های Google Voice» پشتیبانی می‌کند.

Extras

QUERY

رشته‌ای که حاوی پُرسمان جستجو است.

فیلتر هدف نمونه:

<activity android:name=".SearchActivity">
    <intent-filter>
        <action android:name="com.google.android.gms.actions.SEARCH_ACTION"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

انجام جستجوی وب

برای شروع جستجوی وب، از کنش ACTION_WEB_SEARCH استفاده کنید و رشته جستجو را در SearchManager.QUERY اضافی مشخص کنید.

کنش

ACTION_WEB_SEARCH

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

هیچ‌کدام

Extras

SearchManager.QUERY

رشته جستجو.

هدف نمونه:

کاتلین

fun searchWeb(query: String) {
    val intent = Intent(Intent.ACTION_WEB_SEARCH).apply {
        putExtra(SearchManager.QUERY, query)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void searchWeb(String query) {
    Intent intent = new Intent(Intent.ACTION_WEB_SEARCH);
    intent.putExtra(SearchManager.QUERY, query);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

تنظیمات

وقتی برنامه‌تان از کاربر می‌خواهد چیزی را تغییر دهد، برای باز کردن صفحه‌ای در برنامه «تنظیمات سیستم»، از یکی از کنش‌های هدف زیر استفاده کنید:

کنش

ACTION_SETTINGS
ACTION_WIRELESS_SETTINGS
ACTION_AIRPLANE_MODE_SETTINGS
ACTION_WIFI_SETTINGS
ACTION_APN_SETTINGS
ACTION_BLUETOOTH_SETTINGS
ACTION_DATE_SETTINGS
ACTION_LOCALE_SETTINGS
ACTION_INPUT_METHOD_SETTINGS
ACTION_DISPLAY_SETTINGS
ACTION_SECURITY_SETTINGS
ACTION_LOCATION_SOURCE_SETTINGS
ACTION_INTERNAL_STORAGE_SETTINGS
ACTION_MEMORY_CARD_SETTINGS

برای دیدن صفحه‌های تنظیمات اضافی که دردسترس است، به مستندات Settings مراجعه کنید .

طرح‌واره URI داده

هیچ‌کدام

نوع MIME

هیچ‌کدام

هدف نمونه:

کاتلین

fun openWifiSettings() {
    val intent = Intent(Settings.ACTION_WIFI_SETTINGS)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void openWifiSettings() {
    Intent intent = new Intent(Settings.ACTION_WIFI_SETTINGS);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

پیامک زدن

نوشتن پیامک/فراپیام با پیوست کنشی رایج برای برنامه‌های پیام‌رسانی نوشتاری است. بااستفاده از اطلاعات بخش زیر، فیلتر هدفی ایجاد کنید تا توانایی برنامه‌تان را برای انجام این کنش تبلیغ کنید.

نوشتن پیامک/فراپیام با پیوست

برای شروع پیامک یا فراپیام، از یکی از کنش‌های هدف زیر استفاده کنید و جزئیات پیام مثل شماره تلفن، موضوع، و متن پیام را بااستفاده از کلیدهای اضافی زیر مشخص کنید.

کنش

ACTION_SENDTO یا
ACTION_SEND یا
ACTION_SEND_MULTIPLE

طرح‌واره URI داده

sms:<phone_number>

smsto:<phone_number>

mms:<phone_number>

mmsto:<phone_number>

همه این طرح‌ها به یک روش مدیریت می‌شوند.

نوع MIME

"text/plain"

"image/*"

"video/*"

Extras

"subject"

رشته‌ای برای موضوع پیام (معمولاً فقط برای فراپیام).

"sms_body"

رشته‌ای برای پیامک.

EXTRA_STREAM

Uri که به تصویر یا ویدیو موردنظر برای پیوست کردن اشاره می‌کند. اگر از کنش ACTION_SEND_MULTIPLE استفاده می‌کنید، این مورد اضافی ArrayList از Uri شیء است که به تصاویر یا ویدیوهای پیوست‌شده اشاره می‌کند.

هدف نمونه:

کاتلین

fun composeMmsMessage(message: String, attachment: Uri) {
    val intent = Intent(Intent.ACTION_SENDTO).apply {
        type = HTTP.PLAIN_TEXT_TYPE
        putExtra("sms_body", message)
        putExtra(Intent.EXTRA_STREAM, attachment)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void composeMmsMessage(String message, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SENDTO);
    intent.setType(HTTP.PLAIN_TEXT_TYPE);
    intent.putExtra("sms_body", message);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

اگر می‌خواهید مطمئن شوید که هدف شما فقط توسط برنامه پیامک مدیریت می‌شود و نه برنامه‌های ایمیل یا اجتماعی دیگر، از کنش ACTION_SENDTO استفاده کنید و طرح داده "smsto:" را همان‌طور که در مثال زیر نشان داده شده است اضافه کنید:

کاتلین

fun composeMmsMessage(message: String, attachment: Uri) {
    val intent = Intent(Intent.ACTION_SEND).apply {
        data = Uri.parse("smsto:")  // Only SMS apps respond to this.
        putExtra("sms_body", message)
        putExtra(Intent.EXTRA_STREAM, attachment)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void composeMmsMessage(String message, Uri attachment) {
    Intent intent = new Intent(Intent.ACTION_SEND);
    intent.setData(Uri.parse("smsto:"));  // Only SMS apps respond to this.
    intent.putExtra("sms_body", message);
    intent.putExtra(Intent.EXTRA_STREAM, attachment);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="text/plain" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

توجه: اگر درحال توسعه برنامه پیام‌رسانی پیامک/فراپیام هستید، باید فیلترهای هدف را برای چندین کنش اضافی پیاده‌سازی کنید تا بتوانید به‌عنوان برنامه پیامک پیش‌فرض در Android 4.4 و نسخه‌های بالاتر دردسترس باشید. برای کسب اطلاعات بیشتر، به مستندات در Telephony مراجعه کنید.

مرورگر وب

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

بار کردن نشانی وب

کنش‌های گفتاری Google

• «open example.com» (example.com را باز کن)

برای باز کردن صفحه وب، از کنش ACTION_VIEW استفاده کنید و نشانی وب را در داده‌های هدف مشخص کنید.

کنش

ACTION_VIEW

طرح‌واره URI داده

http:<URL>
https:<URL>

نوع MIME

"text/plain"

"text/html"

"application/xhtml+xml"

"application/vnd.wap.xhtml+xml"

هدف نمونه:

کاتلین

fun openWebPage(url: String) {
    val webpage: Uri = Uri.parse(url)
    val intent = Intent(Intent.ACTION_VIEW, webpage)
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}

جاوا

public void openWebPage(String url) {
    Uri webpage = Uri.parse(url);
    Intent intent = new Intent(Intent.ACTION_VIEW, webpage);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

فیلتر هدف نمونه:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <!-- Include the host attribute if you want your app to respond
             only to URLs with your app's domain. -->
        <data android:scheme="http" android:host="www.example.com" />
        <category android:name="android.intent.category.DEFAULT" />
        <!-- The BROWSABLE category is required to get links from web pages. -->
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

نکته: اگر برنامه Android شما عملکردی مشابه وب‌سایتتان ارائه می‌دهد، فیلتر هدفی برای نشانی‌های وبی که به وب‌سایتتان اشاره می‌کنند اضافه کنید. سپس، اگر کاربران برنامه شما را نصب کرده باشند، پیوندهای ایمیل‌ها یا صفحه‌های وب دیگری که به وب‌سایت شما اشاره می‌کنند برنامه Android شما را به‌جای صفحه وب شما باز می‌کنند. در مدیریت پیوندهای برنامه Android بیشتر بدانید.

از Android 12 (سطح API 31) به بعد، هدف وب عمومی فقط درصورتی به فعالیت در برنامه شما منتهی می‌شود که برنامه شما برای دامنه خاص موجود در آن هدف وب تأیید شده باشد. اگر برنامه شما برای دامنه تأیید نشده باشد، هدف وب به‌جای آن به برنامه مرورگر پیش‌فرض کاربر هدایت می‌شود.

درستی‌سنجی کردن هدف‌ها با Android Debug Bridge

برای درستی‌سنجی اینکه برنامه‌تان به هدف‌هایی که می‌خواهید پشتیبانی کنید پاسخ می‌دهد، می‌توانید از ابزار adb برای فعال کردن هدف‌های خاص با انجام کارهای زیر استفاده کنید:

1. دستگاه Android را برای توسعه راه‌اندازی کنید یا از دستگاه مجازی استفاده کنید.
2. نسخه‌ای از برنامه‌تان را نصب کنید که از هدف‌هایی که می‌خواهید پشتیبانی کنید برآید.
3. راه‌اندازی قصد بااستفاده از adb:

   adb shell am start -a <ACTION> -t <MIME_TYPE> -d <DATA> \
     -e <EXTRA_NAME> <EXTRA_VALUE> -n <ACTIVITY>
   

   برای مثال:

   adb shell am start -a android.intent.action.DIAL \
     -d tel:555-5555 -n org.example.MyApp/.MyActivity
   

4. اگر فیلترهای هدف موردنیاز را تعریف کنید، هدف را مدیریت کنید.

برای اطلاعات بیشتر، به صدور فرمان‌های پوسته مراجعه کنید.