העקרונות הבסיסיים של NFC

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

יש שני תרחישי שימוש עיקריים בעבודה עם נתוני NDEF ו-Android:

• קריאת נתוני NDEF מתג NFC
• העברת הודעות NDEF ממכשיר אחד לאחר באמצעות Android BeamTM

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

התכונה Android BeamTM מאפשרת למכשיר לדחוף הודעת NDEF אל על ידי הקשה פיזית על המכשירים ביחד. האינטראקציה הזו מספקת דרך קלה יותר לשלוח נתונים לעומת טכנולוגיות אלחוטיות אחרות, כמו Bluetooth, כי באמצעות NFC, לא נדרשים גילוי או התאמה. החיבור מתחיל באופן אוטומטי כששני מכשירים מגיעים לטווח. Android Beam זמין באמצעות קבוצה של ממשקי API מסוג NFC, כך שכל אפליקציה יכולה לשדר מידע בין מכשירים. לדוגמה, היישומים 'אנשי קשר', 'דפדפן' ו-YouTube משתמשים Android Beam כדי לשתף אנשי קשר, דפי אינטרנט וסרטונים עם מכשירים אחרים.

מערכת שליחת התגים

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

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

1. ניתוח תג ה-NFC וזיהוי סוג ה-MIME או ה-URI שמזהה את המטען הייעודי (payload) של הנתונים בתג.
2. הפיכת סוג ה-MIME או ה-URI והמטען הייעודי (payload) ל-Intent. שתי האפשרויות הראשונות השלבים מתוארים במאמר איך תגי NFC ממופים לסוגי MIME ולמזהי URI.
3. מתחיל פעילות על סמך הכוונה. זה מתואר איך תגי NFC נשלחים לאפליקציות.

איך תגי NFC ממופים לסוגי MIME ולמזהי URI

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

נתוני NDEF עוברים מכסה של הודעה (NdefMessage) שמכילה או יותר רשומות (NdefRecord). כל רשומת NDEF צריכה להיות בפורמט תקין בהתאם המפרט של סוג הרשומה שרוצים ליצור. במכשירי Android תומכים גם בסוגים אחרים של תגים שלא מכילים נתוני NDEF, ואפשר לעבוד איתם באמצעות הכיתות בחבילה android.nfc.tech. מידע נוסף על הטכנולוגיות האלה, ראו את הנושא NFC מתקדם. כדי לעבוד עם סוגי התגים האחרים האלה, לכתוב מחסנית פרוטוקול משלכם כדי לתקשר עם התגים, לכן אנחנו ממליצים להשתמש ב-NDEF כדי להקל על הפיתוח, וכדי לקבל תמיכה מרבית למכשירים מבוססי Android.

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

עכשיו, אחרי שיש לכם קצת רקע בתגי NFC, מתוארים בקטעים הבאים באופן מפורט יותר מערכת Android מטפלת בתגים בפורמט NDEF. כשמכשיר מבוסס Android סורק תג NFC שמכיל NDEF מנתח את ההודעה ומנסה להבין את סוג ה-MIME של הנתונים או לזהות אותו URI. לשם כך, המערכת תקרא את NdefRecord הראשון בתוך NdefMessage כדי לקבוע איך לפרש את כל הודעת ה-NDEF (הודעת NDEF יכולה יש כמה רשומות NDEF). בהודעת NDEF בפורמט תקין, NdefRecord הראשון מכיל את השדות הבאים:

3 -bit TNF (פורמט שם של סוג)

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

סוג אורך משתנה

תיאור סוג הרשומה. אם משתמשים ב-TNF_WELL_KNOWN, מומלץ להשתמש בשדה זה כדי לציין את הערך 'הגדרת סוג רשומה' (RTD). ערכי RTD חוקיים מתוארים בטבלה 2.

מזהה אורך משתנה

מזהה ייחודי של הרשומה. לא משתמשים בשדה הזה לעיתים קרובות, אם צריך לזהות תג באופן ייחודי, אפשר ליצור בשבילו מזהה.

מטען ייעודי (payload) באורך משתנה

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

מערכת שליחת התגים משתמשת בשדות TNF ו-type כדי לנסות למפות סוג MIME או URI אל הודעת NDEF. אם הפעולה בוצעה ללא שגיאות, הוא כולל את המידע הזה בתוך Intent של ACTION_NDEF_DISCOVERED יחד עם המטען הייעודי (Payload) בפועל. אבל, הם מקרים שבהם מערכת שליחת התגים לא יכולה לקבוע את סוג הנתונים על סמך ה-NDEF הראשון רשומה. זה קורה כשלא ניתן למפות את נתוני NDEF לסוג MIME או URI, או כאשר תג NFC לא מכיל נתוני NDEF מלכתחילה. במקרים כאלה, אובייקט Tag שמכיל מידע על הטכנולוגיות של התג והמטען הייעודי (Payload) שלו, נכלל בתוך Intent מסוג ACTION_TECH_DISCOVERED.

בטבלה 1 מתואר איך מערכת שליחת התגים ממפה את סוג ה-TNF ואת הסוג שלו. השדות לסוגי MIME או למזהי URI. הוא גם מתאר אילו TNF אי אפשר למפות לסוג MIME או ל-URI. במקרים כאלה, מערכת שליחת התגים ACTION_TECH_DISCOVERED

לדוגמה, אם מערכת שליחת התגים נתקלת ברשומה מסוג TNF_ABSOLUTE_URI, היא ממפה את שדה סוג האורך המשתנה של אותה רשומה ל-URI. מערכת שליחת התגים כוללת את ה-URI הזה בשדה הנתונים של Intent מסוג ACTION_NDEF_DISCOVERED יחד עם מידע נוסף על התג, כמו המטען הייעודי (payload). לעומת זאת, אם הוא נתקל ברשומה מסוג TNF_UNKNOWN, נוצרת Intent שמכסה את הטכנולוגיות של התג במקום זאת.

טבלה 1. TNF נתמכים והמיפויים שלהם

טבלה 2. ערוצי RTD הנתמכים עבור TNF_WELL_KNOWN ו מיפויים

איך תגי NFC נשלחים לאפליקציות

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

1. ACTION_NDEF_DISCOVERED: ה-Intent הזה משמש כדי להתחיל פעילות כשתג שמכיל מטען ייעודי (payload) של NDEF נסרק והוא מסוג מזוהה. הדבר את Intent עם העדיפות הגבוהה ביותר, ומערכת שליחת התגים תנסה להתחיל פעילות באמצעותה כוונת רכישה לפני כל כוונה אחרת, כשהדבר אפשרי.
2. ACTION_TECH_DISCOVERED: אם לא נרשמו פעילויות לטפל ב-ACTION_NDEF_DISCOVERED כוונה, מערכת שליחת התגים מנסה להפעיל אפליקציה עם כוונה כזו. הזה Intent מתחיל גם באופן ישיר (בלי להפעיל קודם את ACTION_NDEF_DISCOVERED) אם התג שנסרק מכיל נתוני NDEF שלא ניתן למפות לסוג MIME או ל-URI, או אם התג לא מכיל NDEF אבל הוא מסוג טכנולוגיית תגים ידועה.
3. ACTION_TAG_DISCOVERED: ה-Intent הזה התחיל אם אין פעילויות שמטפלות ב-ACTION_NDEF_DISCOVERED או ב-ACTION_TECH_DISCOVERED את הכוונות שלכם.

כך פועלת המערכת הבסיסית לשליחת תגים:

1. כדאי לנסות להתחיל פעילות מתוך הכוונה שנוצרה על ידי מערכת שליחת התגים במהלך ניתוח תג ה-NFC ( ACTION_NDEF_DISCOVERED או ACTION_TECH_DISCOVERED).
2. אם אין מסנן פעילויות לפי הכוונה הזו, אפשר לנסות להתחיל פעילות עם Intent עם העדיפות הנמוכה ביותר (ACTION_TECH_DISCOVERED או ACTION_TAG_DISCOVERED) עד שהאפליקציה תסנן עבור Intent או עד שמערכת שיגור התגים תנסה את כל הכוונות האפשריות.
3. אם לא מתבצע סינון של אפליקציות לפי אובייקט כלשהו של Intent, לא צריך לעשות דבר.

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

בקשת גישה ל-NFC במניפסט של Android

לפני שתהיה לך גישה לחומרת ה-NFC של המכשיר ולטפל כראוי בכוונות NFC, עליך להצהיר על ההצהרות האלה פריטים בקובץ AndroidManifest.xml שלך:

• רכיב ה-<uses-permission> של NFC כדי לגשת לחומרת ה-NFC:

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

• גרסת ה-SDK המינימלית שהאפליקציה שלכם יכולה לתמוך בה. יש תמיכה רק ברמת API 9 שליחת תגים מוגבלת דרך ACTION_TAG_DISCOVERED, ורק מספקת גישה להודעות NDEF באמצעות התוספת EXTRA_NDEF_MESSAGES. לא מאפייני תג אחרים או פעולות קלט/פלט (I/O) אחרים נגישים. רמת API 10 כולל תמיכה מקיפה בקוראים/בכתיבה, וגם דחיפת NDEF בחזית ורמת API 14 מספק דרך קלה יותר לדחוף הודעות NDEF למכשירים אחרים עם Android Beam ופיצ'רים נוספים שיטות נוחות ליצירת רשומות NDEF.

  <uses-sdk android:minSdkVersion="10"/>
  

• הרכיב uses-feature כדי שהאפליקציה תופיע ב-Google Play רק עבור מכשירים עם חומרת NFC:

  <uses-feature android:name="android.hardware.nfc" android:required="true" />
  

  אם האפליקציה שלך משתמשת בפונקציונליות NFC, אבל הפונקציונליות הזו לא חיונית אפשר להשמיט את הרכיב uses-feature ולבדוק את זמינות NFC בכתובת באמצעות בדיקה אם getDefaultAdapter() null.

סינון לפי Intentים של NFC

כדי להפעיל את האפליקציה כשתג NFC שבו אתם רוצים לטפל נסרק, האפליקציה שלכם יכול לסנן לפי אחת מהאובייקטים של Intent של NFC, עבור שתיים או לפי כל שלוש ה-Intent במניפסט של Android. אבל, בדרך כלל רוצים לסנן לפי Intent מסוג ACTION_NDEF_DISCOVERED את רוב השליטה במועד שבו האפליקציה מופעלת. ה-Intent ACTION_TECH_DISCOVERED הוא חלופה ל-ACTION_NDEF_DISCOVERED כשאין אפליקציות שמסננים לפי ACTION_NDEF_DISCOVERED או כאשר המטען הייעודי (Payload) לא נמצא NDEF. הסינון לפי ACTION_TAG_DISCOVERED בדרך כלל כללי מדי קטגוריה לסינון. אפליקציות רבות יסוננו לפי ACTION_NDEF_DISCOVERED או ACTION_TECH_DISCOVERED לפני ACTION_TAG_DISCOVERED, לכן יש סבירות נמוכה של אפליקציה מתחיל. ACTION_TAG_DISCOVERED זמין רק כמוצא אחרון לצורך סינון של אפליקציות במקרים שבהם לא מותקנות אפליקציות אחרות שיכולות לטפל Intent מסוג ACTION_NDEF_DISCOVERED או ACTION_TECH_DISCOVERED.

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

ACTION_NDEF_DISCOVERED

כדי לסנן לפי ACTION_NDEF_DISCOVERED כוונות, צריך להצהיר על מסנן Intent עם סוג הנתונים שרוצים לסנן לפיהם. המסננים הבאים לדוגמה עבור ACTION_NDEF_DISCOVERED Intents עם סוג MIME של text/plain:

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <data android:mimeType="text/plain" />
</intent-filter>

בדוגמה הבאה מתבצע סינון של URI בצורה של https://developer.android.com/index.html

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
    <category android:name="android.intent.category.DEFAULT"/>
   <data android:scheme="https"
              android:host="developer.android.com"
              android:pathPrefix="/index.html" />
</intent-filter>

ACTION_TECH_DISCOVERED

אם הפעילות מסננת לפי Intent ACTION_TECH_DISCOVERED, עליכם ליצור קובץ משאבים בפורמט XML שמציין את הטכנולוגיות שהפעילות שלכם תומכת בהן בתוך קבוצה של tech-list. הפעילות שלכם היא נחשב כהתאמה אם קבוצת tech-list היא קבוצת משנה של הטכנולוגיות נתמך בתג, שניתן לקבל באמצעות קריאה ל-getTechList().

לדוגמה, אם התג שנסרק תומך ב-MifareClassic, NdefFormatable ו-NfcA, קבוצת tech-list חייבת לציין את כל שלוש, שתיים או אחת מהטכנולוגיות (ולא שום דבר אחר) כדי שתהיה התאמה לפעילות שלכם.

בדוגמה הבאה מוגדרות כל הטכנולוגיות. צריך להסיר את אלו שלא נתמך בתג ה-NFC. שומרים את הקובץ (כל שם אפשר לבחור) תיקייה אחת (<project-root>/res/xml).

<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <tech-list>
        <tech>android.nfc.tech.IsoDep</tech>
        <tech>android.nfc.tech.NfcA</tech>
        <tech>android.nfc.tech.NfcB</tech>
        <tech>android.nfc.tech.NfcF</tech>
        <tech>android.nfc.tech.NfcV</tech>
        <tech>android.nfc.tech.Ndef</tech>
        <tech>android.nfc.tech.NdefFormatable</tech>
        <tech>android.nfc.tech.MifareClassic</tech>
        <tech>android.nfc.tech.MifareUltralight</tech>
    </tech-list>
</resources>

אפשר גם לציין כמה קבוצות של tech-list. כל אחד מהtech-list כל קבוצה נחשבת בנפרד, והפעילות שלכם נחשבת כהתאמה אם קבוצת tech-list היא קבוצת משנה של הטכנולוגיות שמוחזרות על ידי getTechList(). כך מתקבלים AND וגם OR סמנטיקה לטכנולוגיות התאמה. הדוגמה הבאה מתאימה לתגים שיכולים לתמוך הטכנולוגיות של NfcA ו-Ndef, או יכולות לתמוך בטכנולוגיות NfcB ו-Ndef:

<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <tech-list>
        <tech>android.nfc.tech.NfcA</tech>
        <tech>android.nfc.tech.Ndef</tech>
    </tech-list>
    <tech-list>
        <tech>android.nfc.tech.NfcB</tech>
        <tech>android.nfc.tech.Ndef</tech>
    </tech-list>
</resources>

בקובץ AndroidManifest.xml, מציינים את קובץ המשאב שיצרתם כרגע ברכיב <meta-data> שבתוך הפונקציה <activity> כמו בדוגמה הבאה:

<activity>
...
<intent-filter>
    <action android:name="android.nfc.action.TECH_DISCOVERED"/>
</intent-filter>

<meta-data android:name="android.nfc.action.TECH_DISCOVERED"
    android:resource="@xml/nfc_tech_filter" />
...
</activity>

למידע נוסף על עבודה עם טכנולוגיות תגים ועל ה-Intent ACTION_TECH_DISCOVERED, אפשר לעיין במאמר עבודה עם תגים נתמכים. טכנולוגיות במסמך Advanced NFC.

ACTION_TAG_DISCOVERED

כדי לסנן לפי ACTION_TAG_DISCOVERED יש להשתמש ב-Intent הבא מסנן:

<intent-filter>
    <action android:name="android.nfc.action.TAG_DISCOVERED"/>
</intent-filter>

קבלת מידע מ-Intent

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

• EXTRA_TAG (חובה): אובייקט Tag שמייצג את התג שנסרק.
• EXTRA_NDEF_MESSAGES (אופציונלי): מערך הודעות NDEF מנותחים מהתג. חובה להוסיף את הפריט הזה בתאריך ACTION_NDEF_DISCOVERED כוונות.
• EXTRA_ID (אופציונלי): המזהה ברמה הנמוכה של התג.

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

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    ...
    if (NfcAdapter.ACTION_NDEF_DISCOVERED == intent.action) {
        intent.getParcelableArrayExtra(NfcAdapter.EXTRA_NDEF_MESSAGES)?.also { rawMessages ->
            val messages: List<NdefMessage> = rawMessages.map { it as NdefMessage }
            // Process the messages array.
            ...
        }
    }
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    ...
    if (NfcAdapter.ACTION_NDEF_DISCOVERED.equals(intent.getAction())) {
        Parcelable[] rawMessages =
            intent.getParcelableArrayExtra(NfcAdapter.EXTRA_NDEF_MESSAGES);
        if (rawMessages != null) {
            NdefMessage[] messages = new NdefMessage[rawMessages.length];
            for (int i = 0; i < rawMessages.length; i++) {
                messages[i] = (NdefMessage) rawMessages[i];
            }
            // Process the messages array.
            ...
        }
    }
}

לחלופין, אפשר לקבל אובייקט Tag מה-Intent, מכילים את המטען הייעודי (payload) ומאפשרים לספור את הטכנולוגיות של התג:

val tag: Tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG)

Tag tag = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);

יצירת סוגים נפוצים של רשומות NDEF

בקטע הזה מוסבר איך ליצור סוגים נפוצים של רשומות NDEF כדי לעזור לכם לכתוב אל תגי NFC או שליחת נתונים באמצעות Android Beam. החל מ-Android 4.0 (רמת API 14), השיטה createUri() זמינה כדי לעזור לך ליצור רשומות URI באופן אוטומטי. החל מ-Android 4.1 (רמת API 16), createExternal() ו-createMime() זמינים כדי לעזור לך ליצור רשומות NDEF ו-MIME מסוג חיצוני. כדאי להשתמש ככל האפשר בשיטות המסייעות האלה כדי להימנע מטעויות כשיוצרים רשומות NDEF באופן ידני.

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

TNF_ABSOLUTE_URI

הערה: מומלץ להשתמש אפשר להקליד RTD_URI במקום זאת של TNF_ABSOLUTE_URI, כי הוא יעיל יותר.

אפשר ליצור רשומת NDEF TNF_ABSOLUTE_URI בדרך הבאה :

val uriRecord = ByteArray(0).let { emptyByteArray ->
    NdefRecord(
            TNF_ABSOLUTE_URI,
            "https://developer.android.com/index.html".toByteArray(Charset.forName("US-ASCII")),
            emptyByteArray,
            emptyByteArray
    )
}

NdefRecord uriRecord = new NdefRecord(
    NdefRecord.TNF_ABSOLUTE_URI ,
    "https://developer.android.com/index.html".getBytes(Charset.forName("US-ASCII")),
    new byte[0], new byte[0]);

מסנן Intent לרשומת ה-NDEF הקודמת ייראה כך:

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:scheme="https"
        android:host="developer.android.com"
        android:pathPrefix="/index.html" />
</intent-filter>

TNF_MIME_MEDIA

אפשר ליצור רשומת NDEF TNF_MIME_MEDIA בדרכים הבאות:

באמצעות השיטה createMime():

val mimeRecord = NdefRecord.createMime(
        "application/vnd.com.example.android.beam",
        "Beam me up, Android".toByteArray(Charset.forName("US-ASCII"))
)

NdefRecord mimeRecord = NdefRecord.createMime("application/vnd.com.example.android.beam",
    "Beam me up, Android".getBytes(Charset.forName("US-ASCII")));

יצירת NdefRecord באופן ידני:

val mimeRecord = Charset.forName("US-ASCII").let { usAscii ->
    NdefRecord(
            NdefRecord.TNF_MIME_MEDIA,
            "application/vnd.com.example.android.beam".toByteArray(usAscii),
            ByteArray(0),
            "Beam me up, Android!".toByteArray(usAscii)
    )
}

NdefRecord mimeRecord = new NdefRecord(
    NdefRecord.TNF_MIME_MEDIA ,
    "application/vnd.com.example.android.beam".getBytes(Charset.forName("US-ASCII")),
    new byte[0], "Beam me up, Android!".getBytes(Charset.forName("US-ASCII")));

מסנן Intent לרשומת ה-NDEF הקודמת ייראה כך:

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="application/vnd.com.example.android.beam" />
</intent-filter>

TNF_WELL_KNOWN עם RTD_TEXT

אפשר ליצור רשומת NDEF TNF_WELL_KNOWN בדרך הבאה:

fun createTextRecord(payload: String, locale: Locale, encodeInUtf8: Boolean): NdefRecord {
    val langBytes = locale.language.toByteArray(Charset.forName("US-ASCII"))
    val utfEncoding = if (encodeInUtf8) Charset.forName("UTF-8") else Charset.forName("UTF-16")
    val textBytes = payload.toByteArray(utfEncoding)
    val utfBit: Int = if (encodeInUtf8) 0 else 1 shl 7
    val status = (utfBit + langBytes.size).toChar()
    val data = ByteArray(1 + langBytes.size + textBytes.size)
    data[0] = status.toByte()
    System.arraycopy(langBytes, 0, data, 1, langBytes.size)
    System.arraycopy(textBytes, 0, data, 1 + langBytes.size, textBytes.size)
    return NdefRecord(NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_TEXT, ByteArray(0), data)
}

public NdefRecord createTextRecord(String payload, Locale locale, boolean encodeInUtf8) {
    byte[] langBytes = locale.getLanguage().getBytes(Charset.forName("US-ASCII"));
    Charset utfEncoding = encodeInUtf8 ? Charset.forName("UTF-8") : Charset.forName("UTF-16");
    byte[] textBytes = payload.getBytes(utfEncoding);
    int utfBit = encodeInUtf8 ? 0 : (1 << 7);
    char status = (char) (utfBit + langBytes.length);
    byte[] data = new byte[1 + langBytes.length + textBytes.length];
    data[0] = (byte) status;
    System.arraycopy(langBytes, 0, data, 1, langBytes.length);
    System.arraycopy(textBytes, 0, data, 1 + langBytes.length, textBytes.length);
    NdefRecord record = new NdefRecord(NdefRecord.TNF_WELL_KNOWN,
    NdefRecord.RTD_TEXT, new byte[0], data);
    return record;
}

מסנן Intent לרשומת ה-NDEF הקודמת ייראה כך:

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="text/plain" />
</intent-filter>

TNF_WELL_KNOWN עם RTD_URI

אפשר ליצור רשומת NDEF TNF_WELL_KNOWN בדרכים הבאות:

באמצעות השיטה createUri(String):

val rtdUriRecord1 = NdefRecord.createUri("https://example.com")

NdefRecord rtdUriRecord1 = NdefRecord.createUri("https://example.com");

באמצעות השיטה createUri(Uri):

val rtdUriRecord2 = Uri.parse("https://example.com").let { uri ->
    NdefRecord.createUri(uri)
}

Uri uri = Uri.parse("https://example.com");
NdefRecord rtdUriRecord2 = NdefRecord.createUri(uri);

יצירת NdefRecord באופן ידני:

val uriField = "example.com".toByteArray(Charset.forName("US-ASCII"))
val payload = ByteArray(uriField.size + 1)                   //add 1 for the URI Prefix
payload [0] = 0x01                                           //prefixes https://www. to the URI
System.arraycopy(uriField, 0, payload, 1, uriField.size)     //appends URI to payload
val rtdUriRecord = NdefRecord(NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_URI, ByteArray(0), payload)

byte[] uriField = "example.com".getBytes(Charset.forName("US-ASCII"));
byte[] payload = new byte[uriField.length + 1];              //add 1 for the URI Prefix
payload[0] = 0x01;                                           //prefixes https://www. to the URI
System.arraycopy(uriField, 0, payload, 1, uriField.length);  //appends URI to payload
NdefRecord rtdUriRecord = new NdefRecord(
    NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_URI, new byte[0], payload);

מסנן Intent לרשומת ה-NDEF הקודמת ייראה כך:

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:scheme="https"
        android:host="example.com"
        android:pathPrefix="" />
</intent-filter>

TNF_EXTERNAL_TYPE

אפשר ליצור רשומת NDEF TNF_EXTERNAL_TYPE בקבצים הבאים דרכים:

באמצעות השיטה createExternal():

var payload: ByteArray //assign to your data
val domain = "com.example" //usually your app's package name
val type = "externalType"
val extRecord = NdefRecord.createExternal(domain, type, payload)

byte[] payload; //assign to your data
String domain = "com.example"; //usually your app's package name
String type = "externalType";
NdefRecord extRecord = NdefRecord.createExternal(domain, type, payload);

יצירת NdefRecord באופן ידני:

var payload: ByteArray
...
val extRecord = NdefRecord(
        NdefRecord.TNF_EXTERNAL_TYPE,
        "com.example:externalType".toByteArray(Charset.forName("US-ASCII")),
        ByteArray(0),
        payload
)

byte[] payload;
...
NdefRecord extRecord = new NdefRecord(
    NdefRecord.TNF_EXTERNAL_TYPE, "com.example:externalType".getBytes(Charset.forName("US-ASCII")),
    new byte[0], payload);

מסנן Intent לרשומת ה-NDEF הקודמת ייראה כך:

<intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:scheme="vnd.android.nfc"
        android:host="ext"
        android:pathPrefix="/com.example:externalType"/>
</intent-filter>

שימוש ב-TNF_EXTERNAL_TYPE לפריסות כלליות יותר של תגי NFC לצורך תמיכה טובה יותר בשני הסוגים מכשירים מבוססי Android וללא Android.

הערה: מזהי URN של TNF_EXTERNAL_TYPE הם בפורמט קנוני: urn:nfc:ext:example.com:externalType, עם זאת, מפרט ה-RTD של פורום NFC מצהירה שיש להשמיט את החלק urn:nfc:ext: של ה-URN רשומת NDEF. לכן כל מה שצריך לספק הוא הדומיין (example.com בדוגמה) ומקלידים (externalType בדוגמה) מופרדים בנקודתיים. כששולחים את TNF_EXTERNAL_TYPE, מערכת Android ממירה את ה-URN של urn:nfc:ext:example.com:externalType ל-URI של vnd.android.nfc://ext/example.com:externalType, מסנן Intent בהצהרה לדוגמה.

רשומות של אפליקציות ל-Android

שהושקה ב-Android 4.0 (רמת API 14), 'רשומת אפליקציה של Android' (AAR) מספקת ודאות שהאפליקציה מופעלת כשתג NFC נסרק. ל-AAR יש את שם החבילה של אפליקציה שמוטמעת ברשומת NDEF. אפשר להוסיף AAR לכל רשומת NDEF של ה-NDEF כי מערכת Android מחפשת מספרי AAR בכל הודעת NDEF. אם התכונה מוצאת AAR, היא תתחיל על סמך שם החבילה ב-AAR. אם האפליקציה לא מופיעה המכשיר, Google Play הושק כדי להוריד את האפליקציה.

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

אם תג מכיל AAR, מערכת שליחת התגים נשלחת באופן הבא:

1. כדאי לנסות להתחיל פעילות באמצעות מסנן Intent כרגיל. אם הפעילות תואמת Intent תואם גם ל-AAR, צריך להתחיל את הפעילות.
2. אם הפעילות שמסננת לפי ה-Intent לא תואמת AAR, אם יש כמה פעילויות שיכולות לטפל בכוונה, או אם אין פעילות שמטפלת בכוונה, מפעילים את: שצוין על ידי ה-AAR.
3. אם אין אפליקציה שיכולה להתחיל ב-AAR, יש לעבור אל Google Play כדי להוריד את על סמך AAR.

הערה: אפשר לבטל את ה-AAR ואת המערכת של Intent כוזב באמצעות בחזית מערכת שליחת הודעות, שמאפשרת לפעילות בחזית תקבל עדיפות כשתג NFC התגלתה. בשיטה הזו, הפעילות חייבת להיות בחזית כדי לעקוף את AAR ואת או מערכת הפצת Intent.

אם אתם עדיין רוצים לסנן לפי תגים סרוקים שלא מכילים AAR, אפשר להצהיר מסנני Intent כרגיל. האפשרות הזו שימושית אם האפליקציה שלך מתעניינת בתגים אחרים לא מכילים AAR. לדוגמה, אולי ברצונך להבטיח שהאפליקציה תטפל תגים קנייניים שאתם פורסים, וגם תגים כלליים שנפרסו על ידי צדדים שלישיים. חשוב לזכור AAR הם ספציפיים למכשירי Android 4.0 ואילך, ולכן כאשר פורסים תגים, סביר להניח כדי להשתמש בשילוב של מזהי AAR וסוגי MIME/URIs כדי לתמוך במגוון הרחב ביותר של מכשירים. לחשבון בנוסף, כאשר פורסים תגי NFC, צריך לחשוב איך תרצו לכתוב את תגי NFC כדי להפעיל אותם תמיכה ברוב המכשירים (מבוססי Android ומכשירים אחרים). כדי לעשות את זה צריך הגדרת סוג MIME או URI ייחודיים יחסית כדי להקל על האפליקציות להבחין ביניהם.

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

val msg = NdefMessage(
        arrayOf(
                ...,
                NdefRecord.createApplicationRecord("com.example.android.beam")
        )
)

NdefMessage msg = new NdefMessage(
        new NdefRecord[] {
            ...,
            NdefRecord.createApplicationRecord("com.example.android.beam")}
        );
)

העברת הודעות NDEF למכשירים אחרים

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

הערה: דחיפת NDEF בחזית הייתה זמינה ברמת API 10, שמספק פונקציונליות דומה ל-Android Beam. מאז ממשקי ה-API האלה הוצאו משימוש, אבל זמינים לתמיכה במכשירים ישנים. מידע נוסף זמין בenableForegroundNdefPush().

ניתן להפעיל את Android Beam לאפליקציה שלכם על ידי שימוש באחת משתי השיטות הבאות:

• setNdefPushMessage(): מקבל NdefMessage כדי להגדיר את ההודעה שיש להעביר. העברה אוטומטית של ההודעה כששני מכשירים קרובים מספיק.
• setNdefPushMessageCallback(): מקבל קריאה חוזרת (callback) שמכיל createNdefMessage() הקריאה הזו נקראת כשמכשיר נמצא בטווח שאליו רוצים להעביר נתונים. הקריאה החוזרת מאפשרת לכם ליצור את הודעת ה-NDEF רק במקרה הצורך.

פעילות יכולה לדחוף רק הודעת NDEF אחת בכל פעם, ולכן setNdefPushMessageCallback() מקבל עדיפות מעל setNdefPushMessage(), אם שתיהן מוגדרות. כדי להשתמש ב- Android Beam, חייבת לעמוד בהנחיות הכלליות הבאות:

• הפעילות שמעבירים את הנתונים חייבת להיות בחזית. שני המכשירים צריכים להיות שהמסכים שלהם נפתחו.
• צריך לבצע אנונימיזציה של הנתונים שמעבירים ב-NdefMessage לאובייקט.
• מכשיר ה-NFC שמקבל את הנתונים שמועברים בסטרימינג חייב לתמוך com.android.npp פרוטוקול NDEF Push או SNEP (Simple NDEF Exchange) פרוטוקול). הפרוטוקול com.android.npp נדרש למכשירים ברמת API 9 (Android) 2.3) לרמת API 13 (Android 3.2). חובה לספק את com.android.npp ואת SNEP ב- רמת API 14 (Android 4.0) ואילך.

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

כדי להפעיל את Android Beam:

1. יצירת NdefMessage שמכיל את ה-NdefRecord שרוצים להעביר למכשיר השני.
2. קוראים לפונקציה setNdefPushMessage() באמצעות NdefMessage, או קוראים ל-setNdefPushMessageCallback שמעבירים אובייקט NfcAdapter.CreateNdefMessageCallback ב-method onCreate() של בפעילות שלכם. כדי להשתמש בשיטות האלה נדרשת פעילות אחת לפחות שברצונך להפעיל ב-Android. Beam, יחד עם רשימה אופציונלית של פעילויות אחרות להפעלה.

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

הדוגמה הבאה ממחישה איך פעילות פשוטה קוראת ל-NfcAdapter.CreateNdefMessageCallback בשיטה onCreate() פעילות (ראו AndroidBeamDemo כדי לקבל את הדגימה המלאה). בדוגמה הזו יש גם שיטות שיעזרו לכם ליצור רשומת MIME:

package com.example.android.beam

import android.app.Activity
import android.content.Intent
import android.nfc.NdefMessage
import android.nfc.NdefRecord
import android.nfc.NfcAdapter
import android.nfc.NfcAdapter.CreateNdefMessageCallback
import android.nfc.NfcEvent
import android.os.Bundle
import android.os.Parcelable
import android.widget.TextView
import android.widget.Toast
import java.nio.charset.Charset

class Beam : Activity(), NfcAdapter.CreateNdefMessageCallback {
    
    private var nfcAdapter: NfcAdapter? = null
    private lateinit var textView: TextView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main)
        textView = findViewById(R.id.textView)
        // Check for available NFC Adapter
        nfcAdapter = NfcAdapter.getDefaultAdapter(this)
        if (nfcAdapter == null) {
            Toast.makeText(this, "NFC is not available", Toast.LENGTH_LONG).show()
            finish()
            return
        }
        // Register callback
        nfcAdapter?.setNdefPushMessageCallback(this, this)
    }

    override fun createNdefMessage(event: NfcEvent): NdefMessage {
        val text = "Beam me up, Android!\n\n" +
                "Beam Time: " + System.currentTimeMillis()
        return NdefMessage(
                arrayOf(
                        createMime("application/vnd.com.example.android.beam", text.toByteArray())
                )
                /**
                 * The Android Application Record (AAR) is commented out. When a device
                 * receives a push with an AAR in it, the application specified in the AAR
                 * is guaranteed to run. The AAR overrides the tag dispatch system.
                 * You can add it back in to guarantee that this
                 * activity starts when receiving a beamed message. For now, this code
                 * uses the tag dispatch system.
                 *///,NdefRecord.createApplicationRecord("com.example.android.beam")
        )
    }

    override fun onResume() {
        super.onResume()
        // Check to see that the Activity started due to an Android Beam
        if (NfcAdapter.ACTION_NDEF_DISCOVERED == intent.action) {
            processIntent(intent)
        }
    }

    override fun onNewIntent(intent: Intent) {
        // onResume gets called after this to handle the intent
        setIntent(intent)
    }

    /**
     * Parses the NDEF Message from the intent and prints to the TextView
     */
    private fun processIntent(intent: Intent) {
        textView = findViewById(R.id.textView)
        // only one message sent during the beam
        intent.getParcelableArrayExtra(NfcAdapter.EXTRA_NDEF_MESSAGES)?.also { rawMsgs ->
            (rawMsgs[0] as NdefMessage).apply {
                // record 0 contains the MIME type, record 1 is the AAR, if present
                textView.text = String(records[0].payload)
            }
        }
    }
}

package com.example.android.beam;

import android.app.Activity;
import android.content.Intent;
import android.nfc.NdefMessage;
import android.nfc.NdefRecord;
import android.nfc.NfcAdapter;
import android.nfc.NfcAdapter.CreateNdefMessageCallback;
import android.nfc.NfcEvent;
import android.os.Bundle;
import android.os.Parcelable;
import android.widget.TextView;
import android.widget.Toast;
import java.nio.charset.Charset;


public class Beam extends Activity implements CreateNdefMessageCallback {
    NfcAdapter nfcAdapter;
    TextView textView;

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        TextView textView = (TextView) findViewById(R.id.textView);
        // Check for available NFC Adapter
        nfcAdapter = NfcAdapter.getDefaultAdapter(this);
        if (nfcAdapter == null) {
            Toast.makeText(this, "NFC is not available", Toast.LENGTH_LONG).show();
            finish();
            return;
        }
        // Register callback
        nfcAdapter.setNdefPushMessageCallback(this, this);
    }

    @Override
    public NdefMessage createNdefMessage(NfcEvent event) {
        String text = ("Beam me up, Android!\n\n" +
                "Beam Time: " + System.currentTimeMillis());
        NdefMessage msg = new NdefMessage(
                new NdefRecord[] { createMime(
                        "application/vnd.com.example.android.beam", text.getBytes())
         /**
          * The Android Application Record (AAR) is commented out. When a device
          * receives a push with an AAR in it, the application specified in the AAR
          * is guaranteed to run. The AAR overrides the tag dispatch system.
          * You can add it back in to guarantee that this
          * activity starts when receiving a beamed message. For now, this code
          * uses the tag dispatch system.
          */
          //,NdefRecord.createApplicationRecord("com.example.android.beam")
        });
        return msg;
    }

    @Override
    public void onResume() {
        super.onResume();
        // Check to see that the Activity started due to an Android Beam
        if (NfcAdapter.ACTION_NDEF_DISCOVERED.equals(getIntent().getAction())) {
            processIntent(getIntent());
        }
    }

    @Override
    public void onNewIntent(Intent intent) {
        // onResume gets called after this to handle the intent
        setIntent(intent);
    }

    /**
     * Parses the NDEF Message from the intent and prints to the TextView
     */
    void processIntent(Intent intent) {
        textView = (TextView) findViewById(R.id.textView);
        Parcelable[] rawMsgs = intent.getParcelableArrayExtra(
                NfcAdapter.EXTRA_NDEF_MESSAGES);
        // only one message sent during the beam
        NdefMessage msg = (NdefMessage) rawMsgs[0];
        // record 0 contains the MIME type, record 1 is the AAR, if present
        textView.setText(new String(msg.getRecords()[0].getPayload()));
    }
}

שימו לב שהקוד הזה גורם להסרת AAR, שניתן להסיר. אם תפעילו את ה-AAR, שהאפליקציה שצוינה ב-AAR תמיד מקבלת את הודעת Android Beam. אם האפליקציה לא כרגע, Google Play מתחיל להוריד את האפליקציה. כלומר, הכוונה הבאה מבחינה טכנית אין צורך במסנן הזה במכשירי Android מגרסה 4.0 ואילך אם נעשה שימוש ב-AAR:

<intent-filter>
  <action android:name="android.nfc.action.NDEF_DISCOVERED"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:mimeType="application/vnd.com.example.android.beam"/>
</intent-filter>

בעזרת מסנן Intent הזה, עכשיו אפשר להתחיל את האפליקציה com.example.android.beam. כשהוא סורק תג NFC או מקבל Android Beam עם מספר AAR של מקלידים com.example.android.beam, או כשהודעה בפורמט NDEF מכילה רשומת MIME מסוג application/vnd.com.example.android.beam.

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