جهات الاتصال

تتيح جهات الاتصال لتطبيق Glassware تلقّي عناصر المخطط الزمني التي لم ينشئها. على المستخدمين مشاركة عنصر في المخطط الزمني بشكلٍ صريح مع جهة الاتصال من خلال النقر على خيار مشاركة في قائمة البطاقة.

آلية عملها

بعد إنشاء جهة اتصال للمشاركة، تتّبع بطاقات المخطط الزمني للمشاركة الخطوات العامة التالية:

1. أنشئ جهة اتصال وحدِّد أنواع MIME التي تتوافق مع جهة الاتصال.
2. أدرِج جهة الاتصال في المخطط الزمني للمستخدم.
3. يتلقّى المستخدم عنصرًا في المخطط الزمني يتضمّن خيار مشاركة في القائمة. يجب أن تسمح Glassware للمستخدمين صراحةً بمشاركة عناصرهم باستخدام عنصر القائمة هذا.
4. ينقر المستخدم على عنصر المخطط الزمني، ثم على خيار القائمة مشاركة، ثم على جهة الاتصال.
5. تنشئ واجهة Mirror API نسخة من بطاقة المخطط الزمني المشتركة، وتمنح جهة الاتصال إذن الوصول إلى النسخة، وتُدرجها في المخطط الزمني للمستخدم. لا يمكن لـ Glassware الوصول إلى عنصر المخطط الزمني الأصلي.
6. إذا اشتركت في تلقّي إشعارات المشاركة، ستتلقّى حمولة تحتوي على معلومات تكشف الهوية لبطاقة المخطط الزمني. يمكنك بعد ذلك استرداد عنصر المخطط الزمني باستخدام Timeline.get.
7. يمكنك تعديل بطاقة المخطط الزمني المشترَك وتعديل بطاقة المخطط الزمني الحالية باستخدام Timeline.update.

حالات الاستخدام

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

هناك طريقتان رئيسيتان يمكن من خلالهما أن تستخدم Glassware جهات الاتصال:

• السماح للمستخدمين بمشاركة عناصر المخطط الزمني مع جهات اتصال أخرى: أضِف عنصر القائمة المضمّن SHARE إلى بطاقة المخطط الزمني. عندما ينقر المستخدمون على عنصر قائمة المشاركة، تعرض Glass قائمة بجهات الاتصال التي يمكن المشاركة معها.

• السماح للمستخدمين بمشاركة عناصر المخطط الزمني مع Glassware: أنشئ جهة اتصال تمثّل Glassware. عندما يريد المستخدمون مشاركة بطاقة مخطط زمني، يظهر جهة اتصالك كخيار. يمكنك أيضًا تحديد قائمة بأنواع MIME المقبولة لكي تظهر جهة الاتصال الخاصة بك فقط في البطاقات التي تهمّك. لتلقّي إشعارات عندما يشارك المستخدمون بطاقة مخطط زمني مع جهة الاتصال الخاصة بك، يمكنك الاشتراك في إشعارات المخطط الزمني.

إنشاء جهة اتصال

للسماح للمستخدمين بمشاركة عناصر المخطط الزمني مع Glassware، أدرِج جهة اتصال عن طريق إرسال تمثيل JSON لجهة اتصال إلى نقطة نهاية REST الخاصة بالإدراج باستخدام طريقة POST.

يجب أن تحدّد جميع جهات الاتصال id، وهو معرّف جهة الاتصال بالنسبة إلى Glassware التي تتلقّى الإشعارات. يجب أيضًا تحديد displayName واحد على الأقل وimageUrls واحد على الأقل، وتستخدم Glass هذه المعلومات لعرض معلومات الاتصال للمستخدم.

ملاحظة: للحصول على أفضل النتائج، استخدِم صورة رمز بتنسيق PNG بحجم 640 × 360 بكسل مع خلفية شفافة لـ imageUrls.

بروتوكول HTTP الأولي

POST /mirror/v1/contacts HTTP/1.1
Authorization: Bearer {auth token}
Content-Type: application/json
Content-Length: {length}

{
  "id": "harold"
  "displayName": "Harold Penguin",
  "iconUrl": "https://developers.google.com/glass/images/harold.jpg"
  "priority": 7
}

الاشتراك في خدمة تلقّي إشعارات المشاركة

تتيح لك واجهة Mirror API الاشتراك في الإشعارات التي يتم إرسالها عندما يتّخذ المستخدم إجراءات معيّنة على عنصر في المخطط الزمني أو عندما يتم تعديل الموقع الجغرافي للمستخدم. عند الاشتراك في تلقّي إشعار، عليك تقديم عنوان URL لبرنامج معالجة سيتم استدعاؤه عند تلقّي الإشعار.

ملاحظة: في مرحلة الإنتاج، يجب أن يكون عنوان URL لمعاودة الاتصال متوافقًا مع طبقة المقابس الآمنة. لأغراض التطوير، نوفّر خادمًا وكيلاً للاشتراك يمكنه إعادة توجيه الإشعارات إلى خادم التطوير غير المتوافق مع بروتوكول SSL.

يتم إرسال إشعار من Mirror API كطلب POST إلى نقطة النهاية التي تم الاشتراك فيها، ويتضمّن نص طلب JSON.

بروتوكول HTTP الأولي

{
  "collection": "timeline",
  "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "operation": "INSERT",
  "userToken": "harold_penguin",
  "verifyToken": "random_hash_to_verify_referer",
  "userActions": [
    {
      "type": "SHARE"
    }
  ]
}

السمة itemId هي ID لعنصر المخطط الزمني المشترَك، ويمكنك استخدامها مع Timeline.get للحصول على عنصر المخطط الزمني. يعرض المثال التالي عنصرًا نموذجيًا في المخطط الزمني مع مرفق صورة:

{
  "id": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "attachments": [
      {
          "contentType": "image/jpeg",
          "id": "<ATTACHMENT_ID>"
      }
  ],
  "recipients": [
      {
          "kind": "glass#contact",
          "source": "api:<SERVICE_ID>",
          "id": "<CONTACT_ID>",
          "displayName": "<CONTACT_DISPLAY_NAME>",
          "imageUrls": [
              "<CONTACT_ICON_URL>"
          ]
      }
  ]
}

يجب أن تستجيب خدمتك لواجهة برمجة التطبيقات باستخدام رمز حالة HTTP‏ 200 OK في حال عدم حدوث أي خطأ. إذا ردّت خدمتك برمز خطأ، قد تحاول واجهة برمجة تطبيقات Mirror إعادة إرسال الإشعار إلى خدمتك.

ملاحظة: ستنتهي مهلة الربط بعد 10 ثوانٍ. إذا كانت العملية تستغرق وقتًا طويلاً، يجب الردّ على الفور وإجراء العملية في سلسلة محادثات أخرى.

تلقّي نص المحادثة

يمكن للمستخدمين مشاركة الكلام المحوّل إلى نص مع جهة الاتصال من خلال قائمة الصوت الرئيسية. يتوفّر حاليًا طلبان صوتيان يمكن لجهة الاتصال استخدامها:

• "تدوين ملاحظة"
• نشر إشعار

على سبيل المثال، يمكن للمستخدم إخبارنا عن عيد ميلاد Chipotle القادم باستخدام العبارة: "Ok Glass... نشر تحديث على... Cat Stream...‎ عيد ميلاد Chipotle غدًا!"

لاستخدام الطلبات الصوتية، اتّبِع الخطوات التالية:

1. حدِّد السمة acceptCommands باستخدام القيمة المناسبة type:

   {
     ...
   
     "displayName": "Cat Stream",
     "id": "CAT_STREAM",
     "acceptCommands": [
       {"type": "POST_AN_UPDATE"}
     ]
   }
   

2. يمكنك الاشتراك في خدمة تلقّي إشعارات على المخطط الزمني لتلقّي إشعار عند توفّر النص المكتوب للكلام. ستتلقّى Glassware إشعارًا عند حدوث ذلك:

   {
     "collection": "timeline",
     "operation": "UPDATE",
     "userToken": "<USER_TOKEN>",
     "verifyToken": "<VERIFY_TOKEN>",
     "itemId": "<ITEM_ID>",
     "userActions": [
       {"type": "LAUNCH"}
     ]
   }
   

3. استخدِم itemId لجلب عنصر المخطط الزمني:

   {
     "id": "<ITEM_ID>",
     "text": "Chipotle's birthday is tomorrow",
     "recipients": [
       {"id": "CAT_STREAM"}
     ]
   }
   

   ملاحظة: عند تلقّي عنصر المخطّط الزمني المشترَك، عدِّل بطاقة المخطّط الزمني الحالية باستخدام Timeline.update بدلاً من إنشاء بطاقة جديدة إذا كنت تعدّل العنصر.

4. إذا سجّل أكثر من Glassware جهة اتصال باستخدام أمر صوتي واحد، ستعرض Glass قائمة من المستوى الثاني تعرض displayName لكل جهة اتصال. يمكن للمستخدمين بعد ذلك التحدث إلى جهة الاتصال التي يختارونها. إذا كانت السمة displayName الخاصة بجهة الاتصال تتضمّن أحرفًا لا يمكن لفظها أو ليست صوتية، استخدِم السمة speakableName لتحديد اللفظ المتوقّع لجهة الاتصال التي تشارك معها.

التعليقات التوضيحية للصور المشترَكة

يمكن للمستخدمين مشاركة الصور مع Glassware مع تضمين تعليق مرافق يكتبونه باستخدام ميزة "الكلام إلى نص". مسار المستخدم العام هو:

1. ينقر المستخدم على عنصر في المخطط الزمني يحتوي على صورة، ويختار عنصر القائمة مشاركة، ثم يختار جهة الاتصال.
2. ينقر المستخدم مرة أخرى خلال فترة زمنية قصيرة لإضافة شرح إلى الصورة.
3. يتحدث المستخدم عن صورة أو فيديو.
4. تتم مشاركة عنصر المخطط الزمني مع Glassware كما هو موضّح سابقًا في قسم طريقة عملها. بالإضافة إلى ذلك، يتم ضبط السمة text الخاصة بعنصر المخطط الزمني باستخدام الترجمة المكتوبة للمستخدم.