توضّح هذه الصفحة كيفية إنشاء إضافة Google Workspace تسمح لمستخدمي "مستندات Google" بمعاينة الروابط من خدمة تابعة لجهة خارجية.
يمكن أن ترصد إضافة Google Workspace روابط الخدمة وتطلب من مستخدمي "مستندات Google" معاينتها. يمكنك ضبط إضافة لمعاينة معاينة أنماط متعدّدة لعناوين URL، مثل الروابط المؤدية إلى طلبات الحصول على الدعم والعملاء المحتملين للمبيعات والملفات الشخصية للموظفين.
كيفية معاينة المستخدمين للروابط
لمعاينة الروابط في مستند على "مستندات Google"، يتفاعل المستخدمون مع الشرائح الذكية والبطاقات:
عندما يكتب المستخدمون عنوان URL أو يلصقونه في مستند، سيطلب منهم "مستندات Google" استبدال الرابط بشريحة ذكية. تعرض الشريحة الذكية رمزًا وعنوانًا قصيرًا أو وصفًا لمحتوى الرابط. وعندما يمرّر المستخدم مؤشر الماوس فوق الشريحة، ستظهر له واجهة بطاقة تعرض مزيدًا من المعلومات عن الملف أو الرابط.
يوضّح الفيديو التالي طريقة تحويل المستخدم لرابط إلى شريحة ذكية ومعاينة بطاقة:
المتطلبات الأساسية
برمجة تطبيقات
- حساب على Google Workspace.
- إضافة على Google Workspace. لإنشاء إضافة، اتّبِع هذا البدء السريع.
Node.js
- حساب على Google Workspace.
- إضافة على Google Workspace. لإنشاء إضافة، اتّبِع هذا البدء السريع.
لغة Python
- حساب على Google Workspace.
- إضافة على Google Workspace. لإنشاء إضافة، اتّبِع هذا البدء السريع.
لغة Java
- حساب على Google Workspace.
- إضافة على Google Workspace. لإنشاء إضافة، اتّبِع هذا البدء السريع.
إجراء اختياري: إعداد المصادقة على خدمة تابعة لجهة خارجية
إذا كانت الإضافة مرتبطة بخدمة تتطلب تفويضًا، يجب على المستخدمين المصادقة على الخدمة لمعاينة الروابط. وهذا يعني أنه عندما يلصق المستخدمون رابطًا من خدمتك في مستند على "مستندات Google" للمرة الأولى، يجب أن تستدعي الإضافة مسار التفويض.
لإعداد خدمة OAuth أو رسالة مطالبة مُخصَّصة للتفويض، يُرجى الاطِّلاع على أحد الأدلة التالية:
إذا أنشأت الإضافة باستخدام "برمجة تطبيقات Google"، راجِع الاتصال بخدمات غير تابعة لشركة Google من خلال إضافة على Google Workspace.
إذا أنشأت الإضافة باستخدام وقت تشغيل مختلف، يُرجى الاطّلاع على ربط الإضافة بخدمة تابعة لجهة خارجية.
إعداد معاينات الروابط للإضافة
يوضّح هذا القسم طريقة إعداد معاينات الروابط للإضافة، والتي تتضمّن الخطوات التالية:
- اضبط معاينات الروابط في مورد النشر أو ملف البيان الخاص بالإضافة.
- أنشئ شريحة ذكية وواجهة الواجهة للروابط.
ضبط معاينات الروابط
لضبط معاينات الروابط، حدِّد الأقسام والحقول التالية في مورد نشر الإضافة أو ملف البيان:
- ضمن القسم
addOns
، أضِف الحقلdocs
لتوسيع "مستندات Google". في الحقل
docs
، نفِّذ عامل التشغيلlinkPreviewTriggers
الذي يتضمّنrunFunction
(تحدّد هذه الدالة في القسم التالي، إنشاء الشريحة الذكية والبطاقة).للتعرّف على الحقول التي يمكنك تحديدها في مشغِّل
linkPreviewTriggers
، يمكنك الاطّلاع على المستندات المرجعية الخاصة بملفات بيان "برمجة تطبيقات Google" أو موارد النشر لأوقات التشغيل الأخرى.في الحقل
oauthScopes
، أضِف النطاقhttps://www.googleapis.com/auth/workspace.linkpreview
حتى يتمكّن المستخدمون من تفويض الإضافة لمعاينة الروابط نيابةً عنهم.
على سبيل المثال، راجِع القسمَين oauthScopes
وaddons
من مورد نشر يضبط معاينات الروابط لخدمة الدعم:
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://www.example.com/images/company-logo.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
}
}
}
في المثال، روابط معاينة إضافة Google Workspace لخدمة طلب الحصول على الدعم الخاصة بالشركة. تحدّد الإضافة ثلاثة أنماط
لعناوين URL لمعاينة الروابط. عندما يتطابق رابط مع أحد أنماط عناوين URL في مستند "مستندات Google"، تنشئ دالة رد الاتصال caseLinkPreview
شريحة وبطاقة ذكية وتعرضها.
إنشاء الشريحة الذكية والبطاقة
لعرض شريحة ذكية وبطاقة لرابط، يجب تنفيذ أي دوال حدّدتها في الكائن linkPreviewTriggers
.
عندما يتفاعل المستخدم مع رابط يتطابق مع نمط عنوان URL محدّد، يتم تنشيط عامل التشغيل linkPreviewTriggers
ويتم تمرير دالة رد الاتصال إلى عنصر الحدث docs.matchedUrl.url
كوسيطة. يمكنك استخدام حمولة هذا الحدث
لإنشاء شريحة ذكية وبطاقة لمعاينة الرابط.
على سبيل المثال، بالنسبة إلى إضافة تحدّد نمط عنوان URL example.com/cases
،
إذا عاين المستخدم الرابط https://www.example.com/cases/123456
، سيتم
عرض حمولة الحدث التالية:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
لإنشاء واجهة البطاقة، يمكنك استخدام التطبيقات المصغّرة لعرض معلومات عن الرابط. يمكنك أيضًا إنشاء إجراءات تتيح للمستخدمين فتح الرابط أو تعديل محتواه. للحصول على قائمة بالأدوات والإجراءات المتاحة، يُرجى الاطلاع على المكوّنات المعتمدة لبطاقات المعاينة.
لإنشاء الشريحة الذكية والبطاقة لمعاينة الرابط:
- نفِّذ الدالة التي حدّدتها في قسم
linkPreviewTriggers
من مورد نشر الإضافة أو ملف البيان:- يجب أن تقبل الدالة عنصر كائن حدث يحتوي على
docs.matchedUrl.url
كوسيطة وتعرض عنصرCard
واحدًا. - إذا كانت الخدمة تتطلّب تفويضًا، يجب أن تستدعي الدالة أيضًا مسار التفويض.
- يجب أن تقبل الدالة عنصر كائن حدث يحتوي على
- لكل بطاقة معاينة، نفِّذ دوال معاودة الاتصال المستخدَمة لتوفير تفاعل الأداة للواجهة. على سبيل المثال، إذا أدرجت زرًا
في الواجهة، يجب أن تحتوي على زر
Action
مرفق ودالة معاودة اتصال يتم تنفيذها عندما يتم النقر على الزر.
ينشئ الرمز التالي دالة معاودة الاتصال caseLinkPreview
:
برمجة تطبيقات
Node.js
لغة Python
لغة Java
المكوّنات المعتمدة لبطاقات المعاينة
تتوافق إضافات Google Workspace مع الأدوات والإجراءات التالية لبطاقات معاينة الرابط:
برمجة تطبيقات
حقل خدمة البطاقة | Type |
---|---|
TextParagraph |
تطبيق مصغّر |
DecoratedText |
تطبيق مصغّر |
Image |
تطبيق مصغّر |
IconImage |
تطبيق مصغّر |
ButtonSet |
تطبيق مصغّر |
TextButton |
تطبيق مصغّر |
ImageButton |
تطبيق مصغّر |
Grid |
تطبيق مصغّر |
Divider |
تطبيق مصغّر |
OpenLink |
الإجراء |
Navigation |
الإجراء هو المتاح فقط باستخدام طريقة updateCard . |
JSON
حقل البطاقة (google.apps.card.v1 ) |
Type |
---|---|
TextParagraph |
تطبيق مصغّر |
DecoratedText |
تطبيق مصغّر |
Image |
تطبيق مصغّر |
Icon |
تطبيق مصغّر |
ButtonList |
تطبيق مصغّر |
Button |
تطبيق مصغّر |
Grid |
تطبيق مصغّر |
Divider |
تطبيق مصغّر |
OpenLink |
الإجراء |
Navigation |
الإجراء متوافق فقط مع updateCard . |
مثال كامل: إضافة طلب الحصول على الدعم
يوضّح المثال التالي إضافة Google Workspace التي تعمل على معاينة الروابط المؤدية إلى طلبات الحصول على الدعم للشركة وملفاتها الشخصية للموظفين.
يوضّح المثال ما يلي:
- رابط المعاينات إلى طلبات الحصول على الدعم، مثل
https://www.example.com/support/cases/1234
. تعرض الشريحة الذكية رمز الدعم، وتشمل بطاقة المعاينة رقم تعريف الطلب ووصفًا. - معاينة روابط وكلاء الدعم، مثل
https://www.example.com/people/rosario-cruz
. تعرض الشريحة الذكية رمزًا لشخص، وتتضمّن بطاقة المعاينة اسم الموظف وعنوان بريده الإلكتروني وعنوانه الوظيفي وصورة ملفه الشخصي. - في حال ضبط لغة المستخدم على الإسبانية، تترجم الشريحة الذكية
labelText
إلى الإسبانية.
مورد النشر
برمجة تطبيقات
{
"timeZone": "America/New_York",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "peopleLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/link-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
},
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}