פורמט של נתוני קובץ מצורף

הדרך הקלה ביותר להוסיף קבצים מצורפים של 'התראות בקרבת מקום' היא מרכז הבקרה של משׂואת רשת (beacon) של Google. לחלופין, אפשר להשתמש ממשק API של אלומת קירבה ופורמט הנתונים של הקבצים המצורפים כפי שמתואר בהמשך.

הערה: יש לפעול בהתאם להתראות בקרבת מקום המדיניות כדי לשמור על חוויה חיובית המשתמשים שלנו.

בקבצים מצורפים של התכונה 'התראות בקרבת מקום' חובה להשתמש מרחב השמות com.google.nearby, וסוג שמורכב משתי אותיות והסיומת האופציונלית -debug.

הפורמט של הקבצים המצורפים צריך להיות JSON. לדוגמה:

    {
      "title": "Example",
      "url": "https://www.example.com"
    }

פורמט JSON מאפשר טירגוט ספציפי יותר, כמו בדוגמה הבאה:

    {
      "title": "Example",
      "url": "https://www.example.com",
      "targeting":[
        {
          "startDate": "2017-01-01",
          "endDate": "2017-01-31",
          "startTimeOfDay": "9:00",
          "endTimeOfDay": "17:00",
          "anyOfDaysOfWeek": [1, 2, 3, 4, 5, 6, 7],
          "anyOfAppInstallStates": ["INSTALLED", "NOT_INSTALLED"]
        }
      ]
    }

כאשר:

• title – שם התוכן. האורך של title צריך להיות קטן יותר מ-40 תווים וחייב להיות קצר מ-50 תווים. במצב אידיאלי, בפני המשתמש קריאה לפעולה. לדוגמה, Order with your phone, skip the line, Set up your thermostat או Learn more about sea otters.
• url – כתובת ה-URL של האפליקציה, האתר או השירות.
• טירגוט – כללים אופציונליים להגבלת החשיפה של התראות בהתאם להקשר של המכשיר.

פורמטים של כתובות URL

התכונה 'התראות בקרבת מקום' תומכת בשלושה פורמטים של כתובות URL:

• כתובת URL
• כוונות האפליקציה
• כוונת אפליקציה בפורמט חופשי

כתובת אתר

כתובת URL היא בדיוק כתובת URL רגילה. כאשר מתקבלת כתובת אתר, הפרמטר המשתמש יתבקש לפתוח את כתובת ה-URL בדפדפן ברירת המחדל. אין אפליקציה מיוחדת נדרשת הגדרה אישית. כתובות URL חייבות להיות בפורמט HTTPS, כתובת URL רגילה:

  https://www.example.com

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

• שימוש ב-HTTP במקום ב-HTTPS
• אסור לקשר לחנות אפליקציות כמו play.google.com. בדף האינטרנט צריך לעמוד בפני עצמו ולהציע מידע שימושי או פעולות ישירות בדף הנחיתה.

כוונת רכישה באפליקציה

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

  intent://host/path#Intent;scheme=yourscheme;package=com.yourapp.ui;end;

לפרטים נוספים על הפורמט של כתובות URL של Intent, אפשר לעיין במאמר אובייקטים של Android עם Chrome. לתשומת ליבכם, תוספות Intent לא עוברות.

אפשר גם ליצור את כתובת ה-URL בצורה תקינה על ידי יצירת Intent, ולאחר מכן שימוש intent.toUri(Intent.URI_INTENT_SCHEME) כפי שמוצג כאן:

    Intent intent = new Intent()
        .setData(new Uri.Builder()
            .scheme("yourscheme")
            .authority("host")
            .appendPath("path")
            .build())
        .setPackage("com.yourapp.ui");
    Log.i(TAG, "Use this intent url: " + intent.toUri(Intent.URI_INTENT_SCHEME));

Intent באפליקציות בפורמט חופשי

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

יש לך אפשרות לשלוח את המשתמש לכתובת URL ספציפית במקום אל חנות Play ב במקרה שהאפליקציה לא מותקנת על ידי הוספת S.browser_fallback_url ל-Intent:

intent://host/path#Intent;scheme=yourscheme;package=com.yourapp.ui; \
  S.browser_fallback_url=http%3A%2F%2Fm.yoursite.com%2Fpath%2F%;end;

טירגוט לפי הקשר

כללים

התכונה 'התראות בקרבת מקום' תומכת בארבעה כללי טירגוט:

• ‫תאריך
• השעה ביום
• היום בשבוע
• מצב ההתקנה של האפליקציה

תאריך

dateStart ו-dateEnd משמשים לציון טווח התאריכים שבו הקובץ המצורף גלוי בפורמט ISO 8601. בדוגמה הבאה מוצגת התראה בחודש ינואר 2017.

    {
      "title": "January 2017",
      "url": "https://www.example.com",
      "targeting":[
        {
          "startDate": "2017-01-01",
          "endDate": "2017-01-31"
        }
      ]
    }

השעה ביום

'timeOfDayStart' וגם 'timeOfDayEnd' משמשים לציון טווח הזמן היומי שבו ניתן לראות את הקובץ המצורף, בפורמט ISO 8601. בדוגמה הבאה מוצגת התראה מדי יום מ-9:00 עד 17:00:

    {
      "title": "Work time",
      "url": "https://www.example.com",
      "targeting":[
        {
          "startTimeOfDay": "9:00",
          "endTimeOfDay": "17:00"
        }
      ]
    }

יום בשבוע

"anyOfDaysOf Week" משמש לציון הימים בשבוע שבהם הקובץ המצורף גלוי. הפורמט הוא ISO 8601, החל מ-1(יום שני) עד 7(יום ראשון). בדוגמה הבאה מוצגת התראה בימים שבת וראשון:

    {
      "title": "Weekends",
      "url": "https://www.example.com",
      "targeting":[
        {
          "anyOfDaysOfWeek": [6, 7]
        }
      ]
    }

מצב ההתקנה של האפליקציה

"anyOfAppInstallStates" היא להגדרת הרשאות גישה לקבצים מצורפים על סמך האפליקציה מצבי ההתקנה. היא פועלת רק לגבי כתובת URL מסוג הפניה לאפליקציה. הבאים בדוגמה שמציגה התראה כשהאפליקציה לא מותקנת.

    {
      "title": "App not installed",
      "url": "intent://host/path#Intent;package=com.example",
      "targeting":[
        {
          "anyOfAppInstallStates": ["NOT_INSTALLED"]
        }
      ]
    }

שילוב של כללים

לכל קובץ מצורף אפשר להגדיר כמה כללי טירגוט. כללים מ- הפונקציה AND חלה על אותו אובייקט טירגוט. הדוגמה הבאה מציג התראה מ-9:00 עד 17:00 בימים שבת וראשון.

    {
      "title": "Weekend and work time",
      "url": "https://www.example.com",
      "targeting":[
        {
          "startTimeOfDay": "9:00",
          "endTimeOfDay": "17:00"
          "anyOfDaysOfWeek": [6, 7]
        }
      ]
    }

כללים מאובייקטי הטירגוט השונים מופרדים באמצעות OR. הבאים לדוגמה מציגה התראה מ-9:00 עד 17:00 מדי יום שני עד שישי, בתוספת כל היום בימי שבת וראשון.

    {
      "title": "Weekend or work time",
      "url": "https://www.example.com",
      "targeting":[
        {
          "anyOfDaysOfWeek": [6, 7]
        },
        {
          "startTimeOfDay": "9:00",
          "endTimeOfDay": "17:00"
        }
      ]
    }

צריך להוסיף מסנן Intent לאפליקציה

צריך להגדיר את האפליקציות כך שיטפלו בסכימה, במארח ובנתיב של כתובת ה-URL הנתונה. לשם כך, צריך להוסיף רכיב בקובץ AndroidManifest.xml כדי להצהיר על <intent-filter> ש תואם לסכימה, למארח ולנתיב, ומסמן אותו לפי קטגוריה מסנן, כפי שמוצג כאן:

  <intent-filter>
    <action android:name="android.intent.action.VIEW"/>
     <!-- both categories below are required -->
     <category android:name="android.intent.category.BROWSABLE"/>
     <category android:name="android.intent.category.DEFAULT"/>
    <data android:host="host"
          android:pathPrefix="/path"
          android:scheme="yourscheme"/>
  </intent-filter>

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