تنسيق بيانات المرفقات

تتمثل أسهل طريقة لإضافة مرفقات "إشعارات الأجهزة المجاورة" في استخدام لوحة بيانات "إشارات Google". بدلاً من ذلك، يمكنك استخدام Proximity Beacon 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 للتطبيق أو موقع الويب أو الخدمة.
  • targeting — قواعد اختيارية للحدّ من ظهور الإشعارات استنادًا إلى سياق الجهاز.

تنسيقات عناوين URL

تتوافق إشعارات الأجهزة المجاورة مع ثلاثة تنسيقات لعناوين URL:

عنوان URL على الويب

عنوان URL على الويب هو عنوان URL العادي بالضبط. عند تلقي عنوان URL ويب، يُطلب من المستخدم فتح عنوان URL في المتصفح الافتراضي. وليست هناك حاجة إلى تهيئة خاصة للتطبيق. يجب أن تستخدم عناوين URL على الويب بروتوكول HTTPS، وأن يتم تنسيقها على شكل عنوان URL عادي:

  https://www.example.com

إذا كان عنوان URL على الويب لا يعرض إشعارًا، فهناك الأسباب المحتملة لذلك على الأرجح:

  • استخدام HTTP بدلاً من HTTPS
  • يحظر الربط بمتجر التطبيقات مثل play.google.com. يجب أن تكون صفحة الويب قائمة بذاتها وأن تقدم معلومات أو إجراءات مفيدة على الصفحة المقصودة مباشرة.

القصد من التطبيق

تُستخدم عناوين URL لقصد التطبيق لتشغيل نية الشراء في أحد التطبيقات. عند تلقي عنوان URL لقصد التطبيق، يستجيب التطبيق المرتبط للمعلمات المضمّنة في عنوان URL، شريطة أن يكون هناك فلتر مطابق لقصد التطبيق. وإذا لم يكن التطبيق مثبتًا، فسيتم نقله إلى متجر Play لتثبيت التطبيق. وبعد تثبيت التطبيق، يمكنه تشغيل التطبيق والمتابعة إلى الميزة التي يحددها مطوّر البرامج. يتم تنسيق عناوين URL المقصودة للتطبيق على النحو التالي:

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

لمزيد من التفاصيل عن تنسيق عناوين URL المقصد منها، يمكنك الاطّلاع على الأجهزة التي تعمل بنظام التشغيل Android Intent باستخدام Chrome. يُرجى العِلم أنّه لا يتمّ تمرير العناصر الإضافية المخصّصة حسب النية بالشراء.

يمكنك أيضًا إنشاء عنوان URL بشكل صحيح من خلال إنشاء هدف، ثم استخدام 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));

القصد من التطبيق المرن

ويجب استخدام هذا الخيار مع أهداف التطبيق التي لا يمكن أن تطابق مخطط المسار والمسار واسم اسم الحزمة. لا تستخدم هذا الخيار إلا إذا كنت متأكدًا من أن عنوان URL المقصود منسق بشكل صحيح.

يمكنك اختيار إرسال المستخدم إلى عنوان 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 صباحًا إلى 5 مساءً يوميًا:

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

اليوم من الأسبوع

يتم استخدام "anyOfDaysOfWeek" لتحديد أيام الأسبوع التي يكون فيها المرفق مرئيًا. التنسيق هو 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"]
        }
      ]
    }

مجموعة من القواعد

يمكن أن تكون هناك قواعد استهداف متعددة لكل مرفق. يتم الجمع بين القواعد من كائن الاستهداف نفسه باستخدام "و". يوضح المثال التالي إشعارًا من 9 صباحًا إلى 5 مساءً في يومي السبت والأحد.

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

تُعتبر القواعد من كائنات الاستهداف المختلفة من نوع ORED. يوضح المثال التالي إشعارًا من 9 صباحًا إلى 5 مساءً من الاثنين إلى الجمعة، بالإضافة إلى يومي طوال أيام السبت والأحد.

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

إضافة فلتر الأهداف إلى تطبيقك

يجب تهيئة التطبيقات للتعامل مع المخطط والمضيف والمسار لعنوان 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>

لمزيد من المعلومات، راجع التعامل مع روابط التطبيقات.