כוונות נפוצות

כוונת רכישה מאפשרת לך להתחיל פעילות באפליקציה אחרת על ידי תיאור של הפעולה שרוצים לבצע, כמו 'הצגת מפה' או "קחו תמונה," באובייקט Intent. סוג זה של Intent נקראת Intent מרומז כי היא לא מציינת את האפליקציה להתחלה, אבל במקום זאת הוא מציין פעולה ומספק חלק מהנתונים שאיתם יש לבצע את הפעולה.

כשמתקשרים אל startActivity() או startActivityForResult() ולהעביר להם כוונה מרומזת, המערכת פתרון את הכוונה לאפליקציה שיכולה לטפל בכוונה ומתחילה Activity התואם. אם יש יותר מאפליקציה אחת שיכולה לטפל בכוונה, המערכת מציגה למשתמש תיבת דו-שיח בוחרים את האפליקציה שרוצים להשתמש בה.

בדף הזה מתוארים כמה כוונות משתמעות שאפשר להשתמש בהן כדי לבצע פעולות נפוצות, שמאורגנות לפי סוג האפליקציה שמטפלת בכוונה. בכל קטע מוסבר גם איך ליצור מסנן כוונה כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה.

זהירות: אם אין במכשיר אפליקציות שיכולות לקבל Intent מרומז, אפליקציה קורסת כשהיא קוראת ל-startActivity(). כדי לאמת קודם קיימת אפליקציה כדי לקבל את הכוונה, צריך לבצע קריאה ל-resolveActivity() באובייקט Intent. אם התוצאה היא לא null, יש לפחות אפליקציה אחת שיכולה לטפל ב-intent, ואפשר לבצע קריאה ל-startActivity() בבטחה. אם התוצאה היא null, לא להשתמש בכוונה ואם אפשר, להשבית את שמעורר את הכוונה.

אם אתם לא יודעים איך יוצרים כוונות או מסנני כוונות, מומלץ קודם לקרוא את המאמר כוונות ומסנני כוונות.

כדי ללמוד איך להפעיל את הכוונות המפורטות בדף הזה מתוך הפיתוח שלכם מארח, לעיון במאמר אימות כוונות באמצעות ניפוי באגים ב-Android קטע של גשר.

פעולות קוליות של Google

Google Voice Actions מפעיל חלק מהכוונות שמפורטות בדף הזה בתגובה לפקודות קוליות. מידע נוסף זמין במאמר תחילת העבודה עם פעולות קוליות במערכת.

שעון מעורר

בהמשך מפורטות פעולות נפוצות באפליקציות של שעון מעורר, כולל המידע שנחוץ לך. כדי ליצור מסנן Intent כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

יצירת התראה

פעולות קוליות של Google

  • "הגדרת שעון מעורר לשעה 7:00"

כדי ליצור שעון מעורר חדש, משתמשים בפעולה ACTION_SET_ALARM ומציינים את פרטי השעון המעורר, כמו השעה וההודעה, באמצעות התוספים הבאים.

הערה: אפשר להציג רק את התוספות של שעות, דקות והודעות ב-Android מגרסה 2.3 (רמת API 9) ומטה. התוספים האחרים זמינים בגרסאות מתקדמות יותר של הפלטפורמה.

פעולה
ACTION_SET_ALARM
Data URI
ללא
סוג MIME
ללא
תוספות
EXTRA_HOUR
השעה להפעלת ההתראה.
EXTRA_MINUTES
הדקות של ההתראה.
EXTRA_MESSAGE
הודעה מותאמת אישית לזיהוי ההתראה.
EXTRA_DAYS
ArrayList כולל כל יום בשבוע שבו ההתראה הזו וחוזרים שלו. צריך להצהיר על כל יום עם מספר שלם מה-Calendar למשל MONDAY.

אם מדובר בהתראה חד-פעמית, אין לציין את התוספת הזו.

EXTRA_RINGTONE
URI של content: שצוין בו רינגטון לשימוש עם ההתראה, או VALUE_RINGTONE_SILENT ללא רינגטון.

כדי להשתמש ברינגטון ברירת המחדל, לא מציינים את התוסף הזה.

EXTRA_VIBRATE
ערך בוליאני שקובע אם ההתראה הזו תפעיל רטט.
EXTRA_SKIP_UI
ערך בוליאני שמציין אם האפליקציה המגיבת חייבת לדלג על ממשק המשתמש שלה כשמגדירים את ההתראה. אם הערך הוא True, האפליקציה צריכה לעקוף כל ממשק משתמש לאישור ולהגדיר את ההתראה שצוינה.

דוגמה לכוונת רכישה:

KotlinJava
fun createAlarm(message: String, hour: Int, minutes: Int) {
    val intent = Intent(AlarmClock.ACTION_SET_ALARM).apply {
        putExtra(AlarmClock.EXTRA_MESSAGE, message)
        putExtra(AlarmClock.EXTRA_HOUR, hour)
        putExtra(AlarmClock.EXTRA_MINUTES, minutes)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}
 
public void createAlarm(String message, int hour, int minutes) {
    Intent intent = new Intent(AlarmClock.ACTION_SET_ALARM)
            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
            .putExtra(AlarmClock.EXTRA_HOUR, hour)
            .putExtra(AlarmClock.EXTRA_MINUTES, minutes);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}
הערה:

כדי להפעיל את הכוונה ACTION_SET_ALARM, לאפליקציה צריכה להיות ההרשאה SET_ALARM:

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

דוגמה למסנן Intent:

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

יצירת טיימר

פעולות קוליות של Google

  • "set timer for 5 minutes"

כדי ליצור טיימר לספירה לאחור, משתמשים בפעולה ACTION_SET_TIMER ומציינים את פרטי הטיימר, כמו משך הזמן, באמצעות התוספים הבאים.

הערה: הכוונה הזו זמינה ב-Android 4.4 (רמת API 19) ואילך.

פעולה
ACTION_SET_TIMER
Data URI
ללא
סוג MIME
ללא
Extras
EXTRA_LENGTH
משך הטיימר בשניות.
EXTRA_MESSAGE
הודעה מותאמת אישית לזיהוי הטיימר.
EXTRA_SKIP_UI
ערך בוליאני שמציין אם האפליקציה המגיבת צריכה לדלג על ממשק המשתמש שלה כשמגדירים את הטיימר. אם הערך הוא True, האפליקציה חייבת לעקוף כל ממשק משתמש לאישור ולהפעיל את הטיימר שצוין.

דוגמה לכוונת רכישה:

KotlinJava
fun startTimer(message: String, seconds: Int) {
    val intent = Intent(AlarmClock.ACTION_SET_TIMER).apply {
        putExtra(AlarmClock.EXTRA_MESSAGE, message)
        putExtra(AlarmClock.EXTRA_LENGTH, seconds)
        putExtra(AlarmClock.EXTRA_SKIP_UI, true)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}
 
public void startTimer(String message, int seconds) {
    Intent intent = new Intent(AlarmClock.ACTION_SET_TIMER)
            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
            .putExtra(AlarmClock.EXTRA_LENGTH, seconds)
            .putExtra(AlarmClock.EXTRA_SKIP_UI, true);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}
הערה:

כדי להפעיל את הכוונה ACTION_SET_TIMER, לאפליקציה צריכה להיות ההרשאה SET_ALARM:

<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />

דוגמה למסנן כוונה:

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

הצג את כל ההתראות

כדי להציג את רשימת ההתראות, משתמשים בפעולה ACTION_SHOW_ALARMS.

לא הרבה אפליקציות מפעילות את הכוונה הזו, כי היא משמשת בעיקר אפליקציות מערכת, אבל כל אפליקציה שמתנהגת כמו שעון מעורר יכולה להטמיע את מסנן הכוונה הזה ולהגיב על ידי הצגת רשימת ההתראות הנוכחיות.

הערה: ה-Intent הזה זמין ב-Android מגרסה 4.4 (רמת API 19) ואילך.

פעולה
ACTION_SHOW_ALARMS
Data URI
ללא
סוג MIME
ללא

דוגמה למסנן Intent:

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

יומן

הוספת אירוע היא פעולה נפוצה באפליקציות יומן. אפשר ליצור מסנן Intent כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו באמצעות בקטע הבא.

איך מוסיפים אירועים ביומן

כדי להוסיף אירוע חדש ליומן של המשתמש, אפשר להשתמש ACTION_INSERT ומציינים את ה-URI של הנתונים באמצעות Events.CONTENT_URI. אחר כך אפשר להשתמש בתוספות הבאות כדי לציין פרטי אירועים שונים.

פעולה
ACTION_INSERT
Data URI
Events.CONTENT_URI
סוג MIME
"vnd.android.cursor.dir/event"
תוספות
EXTRA_EVENT_ALL_DAY
ערך בוליאני שמציין אם מדובר באירוע של יום שלם.
EXTRA_EVENT_BEGIN_TIME
שעת ההתחלה של האירוע (מיליוניות השנייה מאז תחילת התקופה של זמן מערכת).
EXTRA_EVENT_END_TIME
שעת הסיום של האירוע (אלפיות שנייה מאז תחילת התקופה של זמן מערכת).
TITLE
שם האירוע.
DESCRIPTION
תיאור האירוע.
EVENT_LOCATION
מיקום האירוע.
EXTRA_EMAIL
רשימה של כתובות אימייל שמופרדות בפסיקים, שמציינת את המוזמנים.

ניתן לציין פרטי אירועים רבים נוספים באמצעות הקבועים המוגדרים כיתה אחת (CalendarContract.EventsColumns).

דוגמה לכוונת רכישה:

KotlinJava
fun addEvent(title: String, location: String, begin: Long, end: Long) {
    val intent = Intent(Intent.ACTION_INSERT).apply {
        data = Events.CONTENT_URI
        putExtra(Events.TITLE, title)
        putExtra(Events.EVENT_LOCATION, location)
        putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
        putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end)
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivity(intent)
    }
}
 
public void addEvent(String title, String location, long begin, long end) {
    Intent intent = new Intent(Intent.ACTION_INSERT)
            .setData(Events.CONTENT_URI)
            .putExtra(Events.TITLE, title)
            .putExtra(Events.EVENT_LOCATION, location)
            .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
            .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end);
    if (intent.resolveActivity(getPackageManager()) != null) {
        startActivity(intent);
    }
}

דוגמה למסנן כוונה:

<activity ...>
    <intent-filter>
        <action android:name="android.intent.action.INSERT" />
        <data android:mimeType="vnd.android.cursor.dir/event" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

מצלמה

בהמשך מפורטות פעולות נפוצות שקשורות לאפליקציות מצלמה, כולל המידע שנחוץ לך. כדי ליצור מסנן Intent כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

צילום תמונה או סרטון והחזרתם

כדי לפתוח אפליקציית מצלמה ולקבל את התמונה או הסרטון שנוצרו, משתמשים בפעולה ACTION_IMAGE_CAPTURE או ACTION_VIDEO_CAPTURE. ציין גם את מיקום ה-URI שבו לסמן לייק למצלמה כדי לשמור את התמונה או הסרטון, בEXTRA_OUTPUT נוסף.

פעולה
ACTION_IMAGE_CAPTURE או
ACTION_VIDEO_CAPTURE
סכימת URI לנתונים
ללא
סוג MIME
ללא
תוספות
EXTRA_OUTPUT
מיקום ה-URI שבו אפליקציית המצלמה שומרת את קובץ התמונה או הסרטון (כאובייקט Uri).

כשאפליקציית המצלמה חוזרת בהצלחה להתמקד בפעילות שלך. כלומר, האפליקציה מקבלת את הקריאה החוזרת של onActivityResult() — גישה לתמונה או לסרטון ב-URI שציינת עם הערך EXTRA_OUTPUT.

הערה: כשמשתמשים ב-ACTION_IMAGE_CAPTURE כדי לצלם תמונה, המצלמה עשויה להחזיר עותק מוקטן, או תמונה ממוזערת, של התמונה בתוצאה Intent, נשמרה כ-Bitmap בשדה נוסף בשם "data".

דוגמה לכוונת רכישה:

KotlinJava
const val REQUEST_IMAGE_CAPTURE = 1
val locationForPhotos: Uri = ...

fun capturePhoto(targetFilename: String) {
    val intent = Intent(MediaStore.ACTION_IMAGE_CAPTURE).apply {
        putExtra(MediaStore.EXTRA_OUTPUT, Uri.withAppendedPath(locationForPhotos, targetFilename))
    }
    if (intent.resolveActivity(packageManager) != null) {
        startActivityForResult(intent, REQUEST_IMAGE_CAPTURE)
    }
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent) {
    if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == Activity.RESULT_OK) {
        val thumbnail: Bitmap = data.getParcelableExtra("data")
        // Do other work with full size photo saved in locationForPhotos.
        ...
    }
}
 
static final int REQUEST_IMAGE_CAPTURE = 1;
static final Uri locationForPhotos;

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);
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == RESULT_OK) {
        Bitmap thumbnail = data.getParcelableExtra("data");
        // Do other work with full size photo saved in locationForPhotos.
        ...
    }
}

כדי לעשות זאת כשעובדים עם Android מגרסה 12 ואילך (רמת API ‏31 ואילך), אפשר להיעזר בדוגמה הבאה לכוונה.

דוגמה לכוונת רכישה:

KotlinJava
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 מתאים למיקום הפלט, ניתן לקרוא צילום תמונות או צילום סרטונים.

דוגמה למסנן Intent:

<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

  • "Take a picture"

כדי לפתוח אפליקציית מצלמה במצב של תמונת סטילס, משתמשים בפעולה INTENT_ACTION_STILL_IMAGE_CAMERA.

פעולה
INTENT_ACTION_STILL_IMAGE_CAMERA
סכמת URI של נתונים
ללא
סוג MIME
ללא
תוספות
ללא

כוונת רכישה לדוגמה:

KotlinJava
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

  • "record a video"

כדי לפתוח אפליקציית מצלמה במצב וידאו, משתמשים בפעולה INTENT_ACTION_VIDEO_CAMERA.

פעולה
INTENT_ACTION_VIDEO_CAMERA
סכמת URI של נתונים
ללא
סוג MIME
ללא
תוספות
ללא

כוונת רכישה לדוגמה:

KotlinJava
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);
    }
}

דוגמה למסנן Intent:

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

אפליקציית אנשי קשר/אנשים

אלה פעולות נפוצות באפליקציות לניהול אנשי קשר, כולל המידע הדרוש כדי ליצור מסנן כוונה (intent) כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

בחירת איש קשר

כדי לאפשר למשתמש לבחור איש קשר ולתת לאפליקציה גישה לכל הפרטים שלו, צריך להשתמש בפעולה ACTION_PICK ולציין את סוג ה-MIME כ-Contacts.CONTENT_TYPE.

התוצאה Intent שנמסרה לשיחה החוזרת של onActivityResult() כוללת את URI של content: שמצביע לאיש הקשר שנבחר. התגובה מעניקה לאפליקציה הרשאות זמניות לקרוא את איש הקשר הזה באמצעות ה-API של ספק אנשי הקשר, גם אם האפליקציה לא כוללת את ההרשאה READ_CONTACTS.

טיפ: אם אתם צריכים גישה רק לחלק מסוים מהפרטים ליצירת קשר, כמו מספר טלפון או כתובת אימייל, תוכלו לעיין בקטע הבא כדי ללמוד איך לבחור פרטים ספציפיים של אנשי קשר.

פעולה
ACTION_PICK
סכמת URI של נתונים
ללא
סוג MIME
Contacts.CONTENT_TYPE

דוגמה לכוונת רכישה:

KotlinJava
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.
        ...
    }
}

למידע על אופן האחזור של פרטי איש קשר לאחר קבלת ה-URI של איש הקשר, לקרוא את הקטע אחזור פרטים לאיש קשר מסוים.

כשמאתרים את ה-URI של איש הקשר באמצעות הכוונה הזו, בדרך כלל לא צריך את ההרשאה READ_CONTACTS כדי לקרוא פרטים בסיסיים של איש הקשר, כמו השם המוצג והאם איש הקשר מסומן בכוכב. עם זאת, אם אתם מנסים לקרוא נתונים ספציפיים יותר על איש קשר מסוים, כמו מספר הטלפון או כתובת האימייל שלו, אתם צריכים את ההרשאה READ_CONTACTS.

בחירת פרטים ספציפיים ליצירת קשר

כדי לאפשר למשתמש לבחור פרט ספציפי מאיש קשר, כמו מספר טלפון, כתובת אימייל או סוג נתונים אחר, משתמשים בפעולה ACTION_PICK ומציינים את סוג ה-MIME לאחד מסוגי התוכן הבאים, למשל CommonDataKinds.Phone.CONTENT_TYPE כדי לקבל את מספר הטלפון של איש הקשר.

הערה: במקרים רבים, האפליקציה צריכה READ_CONTACTS הרשאה להציג מידע ספציפי על איש קשר מסוים.

אם אתם צריכים לאחזר מאיש קשר רק סוג אחד של נתונים, השיטה הזו כוללת CONTENT_TYPE מ- כיתות ContactsContract.CommonDataKinds יעילות יותר מ- באמצעות Contacts.CONTENT_TYPE, כמו שמוצג בקטע הקודם. התוצאה מספקת גישה ישירה לנתונים הרצויים, בלי שתצטרכו לבצע שאילתה מורכבת יותר ל-Contacts Provider.

התוצאה Intent שנמסרה לשיחה החוזרת של onActivityResult() כוללת את URI של content: שמצביע אל נתוני איש הקשר שנבחרו. התשובה מעניקה לאפליקציה שלך הרשאות זמניות לקרוא את הנתונים של אנשי הקשר, גם אם האפליקציה לא כוללת את ההרשאה READ_CONTACTS.

פעולה
ACTION_PICK
סכמת URI של נתונים
ללא
סוג MIME
CommonDataKinds.Phone.CONTENT_TYPE
בוחרים מאנשי הקשר עם מספר טלפון.
CommonDataKinds.Email.CONTENT_TYPE
בוחרים מאנשי הקשר שיש להם כתובת אימייל.
CommonDataKinds.StructuredPostal.CONTENT_TYPE
לבחור מתוך אנשי קשר שיש להם כתובת למשלוח דואר.

או ערך אחד מתוך ערכים רבים אחרים של CONTENT_TYPE מתחת ל-ContactsContract.

דוגמה לכוונת רכישה:

KotlinJava
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 ומציינים את איש הקשר באמצעות מזהה URI של content: כנתוני הכוונה.

יש שתי דרכים עיקריות לאחזר תחילה את ה-URI של איש הקשר:

  • משתמשים ב-URI של איש הקשר שהוחזר בעקבות הפעולה ACTION_PICK שמוצגת בקטע הקודם. בגישה הזו לא נדרשות הרשאות לאפליקציה.
  • לגשת ישירות לרשימה של כל אנשי הקשר, כפי שמתואר בקטע אחזור רשימה של אנשי קשר. הגישה הזו דורשת את ההרשאה READ_CONTACTS.
פעולה
ACTION_VIEW
סכימת URI לנתונים
content:<URI>
סוג MIME
ללא. המערכת מסיקה את הסוג מה-URI של איש הקשר.

כוונת רכישה לדוגמה:

KotlinJava
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 פעולה, ציון איש הקשר עם URI של content: בתור נתוני הכוונה, ולכלול כל פרט ידוע ליצירת קשר בתוספות שצוינו קבועים ב-ContactsContract.Intents.Insert.

יש שתי דרכים עיקריות לאחזר תחילה את ה-URI של איש הקשר:

  • משתמשים ב-URI של איש הקשר שהוחזר על ידי הפעולה ACTION_PICK שמוצגת בקטע הקודם. הגישה הזו לא דורשת הרשאות לאפליקציה.
  • לגשת ישירות לרשימה של כל אנשי הקשר, כפי שמתואר בקטע אחזור רשימה של אנשי קשר. הגישה הזו דורשת את ההרשאה READ_CONTACTS.
פעולה
ACTION_EDIT
סכימת URI לנתונים
content:<URI>
סוג MIME
הסוג נגזר מה-URI של איש הקשר.
תוספות
לפחות אחת מהתוספות שמוגדרות ב-ContactsContract.Intents.Insert כדי שאפשר יהיה לאכלס את השדות של פרטי איש הקשר.

כוונת רכישה לדוגמה:

KotlinJava
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, מציינים את הערך Contacts.CONTENT_TYPE בתור סוג ה-MIME וכוללים את הפרטים הידועים של איש הקשר בפרטים הנוספים שצוינו על ידי הקבועים ב-ContactsContract.Intents.Insert.

פעולה
ACTION_INSERT
סכמת URI של נתונים
ללא
סוג MIME
Contacts.CONTENT_TYPE
Extras
לפחות אחת מהתוספות שמוגדרות ב-ContactsContract.Intents.Insert.

כוונת רכישה לדוגמה:

KotlinJava
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"
"*/*"
תוספות
Intent.EXTRA_EMAIL
מערך מחרוזות של כל ערכי "To" כתובות אימייל של נמענים.
Intent.EXTRA_CC
מערך מחרוזות של כל ה-"CC" כתובות אימייל של נמענים.
Intent.EXTRA_BCC
מערך מחרוזות של כל השדות 'עותק מוסתר' כתובות אימייל של נמענים.
Intent.EXTRA_SUBJECT
מחרוזת עם נושא האימייל.
Intent.EXTRA_TEXT
מחרוזת עם תוכן האימייל.
Intent.EXTRA_STREAM
Uri שמצביע על הקובץ המצורף. אם משתמשים ACTION_SEND_MULTIPLE פעולה, במקום זאת ArrayList מכיל מספר אובייקטים של Uri.

כוונת רכישה לדוגמה:

KotlinJava
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:", כפי שמתואר בדוגמה הבאה:

KotlinJava
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);
    }
}

דוגמה למסנן 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>

אחסון קבצים

בהמשך מפורטות פעולות נפוצות לאפליקציות לאחסון קבצים, כולל המידע שדרוש לכם כדי ליצור מסנן Intent כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

אחזור של קובץ מסוג ספציפי

כדי לבקש מהמשתמש לבחור קובץ כמו מסמך או תמונה, ולהחזיר קובץ עזר אל את האפליקציה שלך, השתמשו בפעולה ACTION_GET_CONTENT וציינו סוג MIME. ההפניה לקובץ שמוחזרת לאפליקציה היא זמנית במחזור החיים הנוכחי של הפעילות, כך שאם רוצים לגשת אליה מאוחר יותר, צריך לייבא עותק שאפשר יהיה לקרוא מאוחר יותר.

ה-Intent הזה גם מאפשר למשתמש ליצור קובץ חדש בתוך התהליך. עבור למשל, במקום לבחור תמונה קיימת, המשתמש יוכל לצלם תמונה חדשה עם המצלמה.

ה-Intent של התוצאה שנמסרה ל-method onActivityResult() כולל נתונים עם URI שמפנה אל הקובץ. ה-URI יכול להיות כל דבר, כמו URI של http:, URI של file: או content: URI. עם זאת, אם רוצים להגביל את הקבצים שניתן לבחור רק לאלה שזמינים מספק תוכן (מזהה URI מסוג content:) וזמינים כסטרימינג של קבצים באמצעות openFileDescriptor(), צריך להוסיף את הקטגוריה CATEGORY_OPENABLE לכוונה.

ב-Android מגרסה 4.3 ואילך (רמת API 18 ואילך), אפשר גם לאפשר למשתמש לבחור כמה קבצים על ידי הוספת EXTRA_ALLOW_MULTIPLE ל-intent, שמוגדרת כ-true. לאחר מכן אפשר לגשת לכל אחד מהקבצים שנבחרו בClipData אובייקט שהוחזר על ידי getClipData().

פעולה
ACTION_GET_CONTENT
סכמת URI של נתונים
ללא
סוג MIME
סוג ה-MIME שתואם לסוג הקובץ שהמשתמש צריך לבחור.
Extras
EXTRA_ALLOW_MULTIPLE
ערך בוליאני שמצהיר אם המשתמש יכול לבחור יותר מקובץ אחד בכל פעם.
EXTRA_LOCAL_ONLY
ערך בוליאני שמציין אם הקובץ המוחזר חייב להיות זמין ישירות מהמכשיר, במקום שתצטרכו להוריד אותו משירות מרוחק.
קטגוריה (אופציונלי)
CATEGORY_OPENABLE
כדי להחזיר רק "פתוח" קבצים שאפשר לייצג בתור העברת קבצים עם openFileDescriptor().

דוגמה לכוונה לקבלת תמונה:

KotlinJava
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 4.4 ואילך, אפשר לבקש לפתוח קובץ שמנוהל על ידי אפליקציה אחרת באמצעות הפעולה ACTION_OPEN_DOCUMENT וציון סוג MIME. כדי לאפשר למשתמש גם ליצור מסמך חדש שהאפליקציה יכולה לכתוב בו, צריך להשתמש במקום זאת בפעולה ACTION_CREATE_DOCUMENT.

לדוגמה, במקום לבחור מסמכי PDF קיימים, הכוונה ACTION_CREATE_DOCUMENT מאפשרת למשתמשים לבחור איפה הם רוצים ליצור מסמך חדש, למשל באפליקציה אחרת שמנהלת את האחסון של המסמך. לאחר מכן, האפליקציה מקבלת את מיקום ה-URI שבו היא יכולה לכתוב את המסמך החדש.

בעוד שהכוונה (intent) שמועברת לשיטה onActivityResult() מהפעולה ACTION_GET_CONTENT עשויה להחזיר URI מכל סוג, הכוונה (intent) של התוצאה מ-ACTION_OPEN_DOCUMENT ומ-ACTION_CREATE_DOCUMENT תמיד מציינת את הקובץ שנבחר כ-URI מסוג content: שמגובל על ידי DocumentsProvider. אפשר לפתוח את קובץ עם openFileDescriptor() ועם לשלוח שאילתה על הפרטים שלה באמצעות עמודות מהטבלה DocumentsContract.Document.

ה-URI המוחזר מעניק לאפליקציה גישת קריאה לטווח ארוך לקובץ, ויכול להיות גם גישת כתיבה. הפעולה ACTION_OPEN_DOCUMENT שימושית במיוחד כשרוצים לקרוא קובץ קיים בלי ליצור עותק באפליקציה, או כשרוצים לפתוח ולערוך קובץ במקום.

אפשר גם לאפשר למשתמש לבחור כמה קבצים על ידי הוספה EXTRA_ALLOW_MULTIPLE ל-Intent, מוגדר כ-true. אם המשתמש יבחר רק פריט אחד, ניתן לאחזר את הפריט מ-getData(). אם המשתמש יבחר יותר מפריט אחד, הפונקציה getData() תחזיר את הערך null וחובה לבחור במקום זאת לאחזר כל פריט מ-ClipData שמוחזר על ידי getClipData().

הערה: בכוונה חייבים לציין סוג MIME וחייבים להצהיר על הקטגוריה CATEGORY_OPENABLE. אם המיקום ניתן לציין יותר מסוג MIME אחד על ידי הוספת מערך של סוגי MIME עם EXTRA_MIME_TYPES תוספת – אם תעשו זאת, תצטרכו להגדיר את סוג 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().

דוגמה לכוונת רכישה של תמונה:

KotlinJava
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>

במאמר פתיחת קבצים באמצעות framework של גישה לאחסון מוסבר איך לאפשר פתיחה של קבצים שמנוהלים על ידי האפליקציה שלכם מאפליקציות אחרות.

פעולות מקומיות

הזמנת מונית היא פעולה מקומית נפוצה. יוצרים מסנן כוונה כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו, לפי המידע שמפורט בקטע הבא.

הזמנת מונית

פעולות קוליות של Google

  • "get me a Taxi"
  • "call me a car"

(Wear OS בלבד)

כדי להזמין מונית, צריך להשתמש ACTION_RESERVE_TAXI_RESERVATION פעולה.

הערה: אפליקציות חייבות לבקש אישור מהמשתמש לפני השלמת הפעולה הזו.

פעולה
ACTION_RESERVE_TAXI_RESERVATION
Data URI
ללא
סוג MIME
ללא
תוספות
ללא

כוונת רכישה לדוגמה:

KotlinJava
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>

מפות

הצגת מיקום במפה היא פעולה נפוצה באפליקציות מפות. אפשר ליצור מסנן Intent כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו באמצעות בקטע הבא.

הצגת מיקום במפה

כדי לפתוח מפה, משתמשים בפעולה ACTION_VIEW ומציינים את פרטי המיקום בנתוני ה-Intent באחת מהסכימות הבאות.

פעולה
ACTION_VIEW
סכימת URI לנתונים
geo:latitude,longitude
הצג את המפה בקו האורך ובקו הרוחב הנתונים.

דוגמה: "geo:47.6,-122.3"

geo:latitude,longitude?z=zoom
הצגת המפה בקווי האורך והרוחב שצוינו ברמת זום מסוימת. רמת זום של 1 מציג את כדור הארץ כולו, במרכז בנקודת הזמן קו רוחב,lng. הערך הגבוה ביותר רמת הזום (הקרובה ביותר) היא 23.

דוגמה: "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"

הערה:כל המחרוזות שמועברות ב-URI geo חייבות להיות מקודדים. לדוגמה, המחרוזת 1st & Pike, Seattle הופכת 1st%20%26%20Pike%2C%20Seattle. הרווחים במחרוזת מקודדים באמצעות %20 או הוחלף בסימן הפלוס (+).

סוג MIME
ללא

כוונת רכישה לדוגמה:

KotlinJava
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 ואז לציין את מיקום ה-URI של הקובץ בנתוני Intent.

פעולה
ACTION_VIEW
סכימת URI לנתונים
file:<URI>
content:<URI>
http:<URL>
סוג MIME
"audio/*"
"application/ogg"
"application/x-ogg"
"application/itunes"
או כל שירות אחר שנחוץ לאפליקציה.

כוונת רכישה לדוגמה:

KotlinJava
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);
    }
}

דוגמה למסנן 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 להגבילie jean"

כדי להשמיע מוזיקה בהתאם לשאילתת חיפוש, משתמשים Intent מסוג INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH. אפליקציה מסוימת עשויה להיות מופעלת כוונה כזו בתגובה לפקודה הקולית של המשתמש להשמיע מוזיקה. האפליקציה המקבלת של הכוונה הזו מבצעת חיפוש במלאי שטחי הפרסום שלה כדי להתאים תוכן קיים לשאילתה הנתונה, ומתחילה להפעיל את התוכן הזה.

ב-Intent הזה, צריך לכלול את המחרוזת EXTRA_MEDIA_FOCUS נוסף, שמציין את מצב החיפוש המיועד. לדוגמה, מצב החיפוש יכול לציין החיפוש הוא שם של אומן או של שיר.

פעולה
INTENT_ACTION_MEDIA_PLAY_FROM_SEARCH
סכמת URI של נתונים
ללא
סוג MIME
ללא
תוספות
MediaStore.EXTRA_MEDIA_FOCUS (שדה חובה)

מציין את מצב החיפוש: אם המשתמש מחפש אומן, אלבום, שיר או או פלייליסט. ברוב מצבי החיפוש נדרשים פרטים נוספים. לדוגמה, אם המשתמש מעוניין להאזין לשיר מסוים, יכול להיות שהכוונה כוללת שלוש תוספות נוספות: שם השיר, האומן והאלבום. Intent זה תומך במצבי החיפוש הבאים עבור כל ערך של 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 (חובה): מחרוזת שמכילה כל שילוב של האלבום, האומן, הז'אנר או השם. תוספת זו תמיד ניתנת עבור תאימות לאחור. אפליקציות קיימות שלא יודעות על מצבי החיפוש יכולות לעבד את זה Intent כחיפוש לא מובנה.

פלייליסט – Audio.Playlists.ENTRY_CONTENT_TYPE

הפעלת פלייליסט מסוים או פלייליסט שתואם לקריטריונים מסוימים שצוינו על ידי תכונות נוספות.

תוספות נוספות:

  • EXTRA_MEDIA_ALBUM: האלבום.
  • EXTRA_MEDIA_ARTIST: האומן.
  • "android.intent.extra.genre": הז'אנר.
  • "android.intent.extra.playlist": הפלייליסט.
  • EXTRA_MEDIA_TITLE: שם השיר שהפלייליסט על סמך.
  • QUERY (חובה): מחרוזת שמכילה שילוב כלשהו של האלבום, האומן, הז'אנר, הפלייליסט או השם שלו. האפשרות הזו תמיד קיימת לטובת תאימות לאחור. אפליקציות קיימות שלא מכירים את מצבי החיפוש יכולים לעבד את הכוונה הזו כחיפוש לא מובנה.

כוונת רכישה לדוגמה:

אם המשתמש רוצה להאזין למוזיקה של אומן מסוים, אפליקציית חיפוש עשויה ליצור את כוונת החיפוש הבאה:

KotlinJava
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 כדי לקבוע את מצב החיפוש. אחרי שהפעילות מזוהה במצב החיפוש, קוראים את הערכים של התוספות הנוספות שבמצב החיפוש המסוים. בעזרת המידע הזה, האפליקציה יכולה לבצע את החיפוש במלאי שטחי הפרסום שלה כדי להפעיל את תוכן שתואם לשאילתת החיפוש. הדוגמה הבאה ממחישה זאת.

KotlinJava
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
"*/*"
תוספות
EXTRA_NAME
מחרוזת שמציינת את הכותרת או את הנושא של ההערה.
EXTRA_TEXT
מחרוזת שמציינת את הטקסט של ההערה.

כוונת רכישה לדוגמה:

KotlinJava
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 ולציין את מספר הטלפון באמצעות את סכימת ה-URI הבאה. כשאפליקציית הטלפון נפתחת, מוצג מספר הטלפון, והמשתמש צריך להקיש על הלחצן שיחה כדי להתחיל את שיחת הטלפון.

פעולות קוליות של Google

  • "call 555-5555"
  • "call bob"
  • "call voicemail"

כדי לבצע שיחת טלפון ישירות, צריך להשתמש בפעולה ACTION_CALL ומציינים מספר טלפון באמצעות סכימת ה-URI הבאה. כשאפליקציית הטלפון נפתחת, היא מתחיל את שיחת הטלפון. המשתמש לא צריך להקיש על הלחצן שיחה.

כדי לבצע את הפעולה 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().

דוגמה לכוונת רכישה:

KotlinJava
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);
    }
}

בהמשך מפורטות פעולות נפוצות באפליקציות חיפוש, כולל המידע הדרוש כדי ליצור מסנן כוונה (intent) כדי לפרסם את היכולת של האפליקציה לבצע כל פעולה.

חיפוש באמצעות אפליקציה ספציפית

פעולות קוליות של Google

  • "search for cat videos on myvideoapp"

כדי לתמוך בחיפוש בהקשר של האפליקציה, צריך להצהיר על מסנן Intent באפליקציה עם הפעולה SEARCH_ACTION, כפי שמתואר בדוגמה הבאה של מסנן Intent.

הערה: לא מומלץ להשתמש ב-SEARCH_ACTION לחיפוש אפליקציות. במקום זאת, מטמיעים את GET_THING כדי לנצל את התמיכה המובנית של Google Assistant בחיפוש מתוך האפליקציה. מידע נוסף זמין במאמר הבא: Google Assistant תיעוד של פעולות באפליקציה.

פעולה
"com.google.android.gms.actions.SEARCH_ACTION"
לתמוך בשאילתות חיפוש מ'פעולות קוליות' של Google.
תוספות
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
ללא
תוספות
SearchManager.QUERY
מחרוזת החיפוש.

דוגמה לכוונת רכישה:

KotlinJava
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);
    }
}

הגדרות

כדי לפתוח מסך באפליקציית הגדרות המערכת כשהאפליקציה מחייבת את המשתמש לשנות משהו: להשתמש באחת מפעולות 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
ללא

כוונת רכישה לדוגמה:

KotlinJava
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);
    }
}

העברת הודעות טקסט

כתיבת הודעת SMS/MMS עם קובץ מצורף היא פעולה נפוצה באפליקציות הודעות טקסט. יוצרים מסנן כוונה כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו, לפי המידע שמפורט בקטע הבא.

כתיבת הודעת SMS/MMS עם קובץ מצורף

כדי לשלוח הודעת טקסט מסוג SMS או MMS, משתמשים באחת מפעולות הכוונה הבאות ומציינים את פרטי ההודעה, כמו מספר הטלפון, הנושא וגוף ההודעה, באמצעות המקשים הנוספים הבאים.

פעולה
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/*"
תוספות
"subject"
מחרוזת של נושא ההודעה (בדרך כלל ל-MMS בלבד).
"sms_body"
מחרוזת להודעת הטקסט.
EXTRA_STREAM
A Uri שמצביע אל תמונה או סרטון לצירוף. אם משתמשים בפעולה ACTION_SEND_MULTIPLE, האפשרות הנוספת הזו היא ArrayList של אובייקטים מסוג Uri שמפנים לתמונות או לסרטונים שרוצים לצרף.

דוגמה לכוונת רכישה:

KotlinJava
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:" כמו בדוגמה הבאה:

KotlinJava
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);
    }
}

דוגמה למסנן 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>

הערה: אם מפתחים אפליקציה להעברת הודעות SMS/MMS, צריך להטמיע מסנני Intent לכמה פעולות נוספות כדי שיהיו זמינים אפליקציית ברירת המחדל ל-SMS ב-Android 4.4 ואילך. למידע נוסף, עיינו במסמכי התיעוד ב-Telephony.

דפדפן אינטרנט

טעינת כתובת URL של אתר היא פעולה נפוצה באפליקציות של דפדפני אינטרנט. אפשר ליצור מסנן Intent כדי לפרסם את היכולת של האפליקציה לבצע את הפעולה הזו באמצעות בקטע הבא.

טעינת כתובת URL

פעולות קוליות של Google

  • "open example.com"

כדי לפתוח דף אינטרנט, משתמשים בפעולה ACTION_VIEW ומציינים את כתובת ה-URL של האתר בנתוני הכוונה.

פעולה
ACTION_VIEW
סכימת URI לנתונים
http:<URL>
https:<URL>
סוג MIME
"text/plain"
"text/html"
"application/xhtml+xml"
"application/vnd.wap.xhtml+xml"

דוגמה לכוונת רכישה:

KotlinJava
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 מספקת פונקציונליות דומה לאתר שלכם, כדאי לכלול מסנן Intent לכתובות URL שמפניות לאתר שלכם. לאחר מכן: אם המשתמשים התקינו את האפליקציה, קישורים מהודעות אימייל או מדפי אינטרנט אחרים שמפנים לאתר שלכם פותחים את האפליקציה ל-Android במקום את דף האינטרנט. מידע נוסף זמין ב- הטיפול בקישורים לאפליקציות ל-Android.

החל מ-Android 12 (רמת API 31), אובייקט Intent גנרי באינטרנט מוביל פעילות באפליקציה שלך רק אם האפליקציה אושרה לדומיין הספציפי שכלולה בכוונת האינטרנט. אם האפליקציה לא אושרה עבור הדומיין, האינטרנט Intent עובר לאפליקציית הדפדפן שהוגדרה כברירת מחדל של המשתמש.

אימות כוונות באמצעות Android Debug Bridge

כדי לוודא שהאפליקציה שלכם מגיבה לכוונות שאתם רוצים לתמוך בהן, תוכלו להשתמש בכלי adb כדי להפעיל כוונות ספציפיות:

  1. מגדירים מכשיר Android לפיתוח או משתמשים במכשיר וירטואלי.
  2. מתקינים גרסת אפליקציה שמטפלת בכוונות שאתם רוצים לתמוך בהן.
  3. הפעלת Intent באמצעות 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. אם מגדירים את מסנני ה-Intent הנדרשים, צריך לטפל ב-Intent.

מידע נוסף זמין במאמר הרצת פקודות מעטפת.