sell zaf app scaffold

إطار عمل تطبيق Zendesk (ZAF) React Skeleton لبيع التطبيقات

تسمح لك الحزمة بتمهيد تطبيق قائم على React، ومتكامل مع Zendesk App Framework (ZAF)، وتمكنك من البدء بسرعة في تطوير التطبيقات لـ Zendesk Sell.

ملاحظة: تستند المستندات إلى دليل مطور Zendesk. أنها تحتوي فقط على المعلومات المحددة والتي نأمل أن تكون ضرورية فيما يتعلق بإنشاء تطبيق متكامل مع Zendesk Sell. إذا كنت تواجه مشكلة ما أو لم تكن هناك معلومات كافية هنا، فيرجى زيارة الوثائق الفعلية.

متطلبات الملف

يجب تضمين بنية المجلد والملفات التالية في التطبيق لتثبيت التطبيق بنجاح في منتج Zendesk:

 assets/
  logo.png
  logo-small.png
translations/
  en.json
manifest.json

وفيما يلي وصف مختصر للملفات المطلوبة:

• Manifest.json - يصف التطبيق ويكوّنه. انظر المرجع الواضح.
• Translations/en.json - ملف ترجمة إنجليزي قياسي. انظر التدويل.
• الأصول/logo-small.png (128x128px) - أيقونة صغيرة تظهر في رأس التطبيق. راجع أيقونات التطبيقات لمعرفة مواصفات الصورة.
• الأصول/logo.png (320x320px) - أيقونة كبيرة معروضة في صفحات إدارة Zendesk لإدارة التطبيقات. راجع أيقونات التطبيقات لمعرفة مواصفات الصورة.

مثال لبيان تطبيق HubSpot for Sell:

{
  "name" : " Hubspot " ,
  "author" : {
    "name" : " Zendesk " ,
    "email" : " [email protected] " ,
    "url" : " https://www.zendesk.com "
  },

  "defaultLocale" : " en " ,
  "private" : false ,
  "singleInstall" : true ,

  "location" : {
    "sell" : {
      "lead_card" : {
        "url" : " assets/index.html "
      },
      "person_card" : {
        "url" : " assets/index.html "
      },
      "company_card" : {
        "url" : " assets/index.html "
      }
    }
  },

  "version" : " 2.0.3 " ,
  "frameworkVersion" : " 2.0 " ,

  "parameters" : [
    {
      "name" : " access_token " ,
      "type" : " oauth "
    }
  ],

  "oauth" : {
    "client_id" : " {Client ID} " ,
    "client_secret" : " {Client Secret} " ,
    "authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
    "access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
    "scope" : " contacts content oauth "
  }
}

تحديد موقع التطبيق

يجب عليك الإعلان عن المكان الذي تريد أن يظهر فيه تطبيقك في كل واجهة منتج باستخدام خاصية location في البيان.json. المواقع هي التي يمكن أن تظهر فيها إطارات iframe في المنتج. يمكنك تحديد موقع واحد أو أكثر في منتج Zendesk واحد أو أكثر. افتراضيًا، سيكون تطبيقك متاحًا في Zendesk Sell على جميع بطاقات الكائنات (العميل المحتمل، جهة الاتصال، الصفقة) في اللوحة الموجودة على الجانب الأيمن.

 "location" : {
  "sell" : {
    "lead_card" : {
      "url" : " assets/index.html "
    },
    "person_card" : {
      "url" : " assets/index.html "
    },
    "company_card" : {
      "url" : " assets/index.html "
    },
    "deal_card" : {
      "url" : " assets/index.html "
    }
  }
}

للتعرف على المواقع المتاحة، راجع Sell Apps API. لمعرفة المزيد حول تعيين موقع التطبيق، قم بزيارة قسم إعداد موقع التطبيق في دليل المطور.

الأمن والمصادقة

عندما يقوم أحد التطبيقات بتقديم طلبات AJAX، يمكن عرض إعدادات الطلب في وحدة تحكم المتصفح. قد تحتوي بعض الإعدادات على معلومات حساسة مثل مفتاح API أو الرمز المميز. إحدى الطرق الموصى بها لمنع هذا السلوك هي استخدام OAuth Authentication . يمكن أن يكون الخيار الآخر هو استخدام Secure Settings . اختر أي خيار يناسبك.

مصادقة OAuth

يمكنك استخدام OAuth2 لمصادقة جميع طلبات واجهة برمجة التطبيقات (API) الخاصة بك لخدمة خارجية. يوفر OAuth طريقة آمنة لتطبيقك للوصول إلى بيانات حسابك دون الحاجة إلى إرسال معلومات حساسة مثل أسماء المستخدمين وكلمات المرور مع الطلبات. لاستخدام مصادقة OAuth، يتعين عليك تسجيل تطبيقك مع خدمة جهة خارجية لإنشاء بيانات اعتماد OAuth لتطبيقك. تحتاج أيضًا إلى إضافة بعض الوظائف إلى التطبيق الخاص بك لتنفيذ تدفق ترخيص OAuth.

تسجيل التطبيق مع خدمة الطرف الثالث

عند تسجيل تطبيق ما، ستظهر لك شاشة تعرض إعدادات تطبيقك الجديد بما في ذلك اسم التطبيق والوصف ومعلومات التطبيق الأخرى التي يجب عليك ملؤها. بالإضافة إلى ذلك، ستجد أيضًا إعدادات المصادقة لـ تطبيقك مثل معرف العميل، وسر العميل، وعنوان URL لإعادة التوجيه، بالإضافة إلى النطاقات التي يستخدمها تطبيقك. ستحتاج إلى هذه العناصر عند بدء اتصال OAuth بين تطبيقك وخدمة الطرف الثالث.

• Client ID - هذا المعرف فريد لتطبيقك ويستخدم لبدء OAuth.
• Client secret - يستخدم لإنشاء وتحديث مصادقة OAuth.
• Redirect URL - ستتم إعادة توجيه المستخدمين إلى هذا الموقع بعد منح حق الوصول إلى تطبيقك. استخدم أحد عناوين URL التالية:
  • https://zis.zendesk.com/api/services/zis/connections/oauth/callback (عند الإنتاج)
  • https://zis.zendesk-staging.com/api/services/zis/connections/oauth/callback (عند التدريج)
• Scope - إجراء أمني اختياري. يحدد النطاق البيانات التي يحق لتطبيقك الوصول إليها.
• OAuth URL - سيحتاج المستخدم إلى عنوان URL هذا لتوصيل تطبيقك. يتم إنشاء عنوان URL استنادًا إلى بيانات اعتماد عميل تطبيقك، وعنوان URL لإعادة التوجيه، وتكوين النطاقات.

استخدم Client ID Client secret في التطبيق الخاص بك كما هو موضح في هذا القسم التالي.

تنفيذ OAuth في التطبيق

بمجرد تسجيل تطبيقك، يجب عليك تحديد إعدادات OAuth في ملف manifest.json . قم بتحديث client_id و client_secret بما لديك.

 "oauth" : {
  "client_id" : " {Client ID} " ,
  "client_secret" : " {Client Secret} " ,
  "authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
  "access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
  "scope" : " contacts content oauth "
}

تحتاج أيضًا إلى إضافة معلمة من النوع "oauth" إلى قائمة المعلمات:

 "parameters" : [
  {
    "name" : " access_token " ,
    "type" : " oauth "
  }
]

لمزيد من المعلومات قم بزيارة المستندات

رمز وصول OAuth

في رمز تطبيقك، استخدم العنصر النائب {{setting.access_token}} وخاصية secure: true لتقديم طلب OAuth.

 var settings = {
  url : 'https://www.example.com/api/user' ,
  headers : { "Authorization" : "Bearer {{setting.access_token}}" } ,
  secure : true ,
  type : 'GET'
} ;
var client = ZAFClient . init ( ) ;
client . request ( settings ) . then ( ... ) ;

تنسيق الطلب

هذه واجهة برمجة تطبيقات JSON فقط. يجب عليك توفير Content-Type: application/json رأسًا على طلبات PUT وPOST. يجب عليك تعيين رأس Accept: application/json لجميع الطلبات.

 var settings = {
  url : 'https://www.example.com/api/user' ,
  dataType : 'json' ,
  contentType : 'application/json' ,
  ...
} ; 

إعدادات آمنة

تعد الإعدادات الآمنة طريقة أخرى لجعل الإعدادات غير قابلة للوصول إلى الوكلاء عند تقديم طلبات AJAX. يتم إدراج قيم الإعداد فقط في جانب خادم الطلب الصادر في طبقة الوكيل. راجع استخدام الإعدادات الآمنة لإعدادها.

باستخدام حديقة Zendesk

بينما يمكنك استخدام أي CSS مخصص أو إطار عمل أمامي لشكل ومظهر تطبيقك، توصي Zendesk باستخدام Zendesk Garden. تم تصميم Zendesk Garden ليكون خط أساس مشترك للأنماط والمكونات بين جميع منتجات Zendesk. لجعل تطبيقك مطابقًا لشكل ومظهر Zendesk، يتم استخدام Zendesk Garden في التطبيق كإعداد افتراضي.

مثال:

. YourElement {
  color : var ( --zd-color-green-600 );
  padding : var ( --zd-spacing-sm );
}

لمزيد من المعلومات حول فئات CSS ومكونات React في Zendesk Garden، راجع Garden.zendesk.com.

عميل ZAF

يتيح عميل ZAF لتطبيقك الموجود في iframe التواصل مع منتج Zendesk المضيف. يمكنك استخدام العميل في تطبيقاتك للاستماع إلى الأحداث واستدعاء الإجراءات والوصول إلى الخصائص في كل موقع. راجع دليل ZAF Client API.

مثال:

 const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
  console . log ( data ) // { "contact.email": "[email protected]" }
} )

@zendesk/sell-zaf-app-toolbox

توفر حزمة @zendesk/sell-zaf-app-toolbox مجموعة من الأساليب والخطافات والمكونات المفيدة التي تساعدك على إنشاء تطبيقات React متكاملة مع Zendesk Sell بشكل أسرع وبجهد أقل. يستخدمون عميل Zendesk's App Framework Client تحت الغطاء. لمعرفة المزيد قم بزيارة المستودع.

اختبار التطبيق محليا

1. استخدم واجهة سطر الأوامر الخاصة بك، وانتقل إلى المجلد الذي يحتوي على التطبيق الذي تريد اختباره.

2. تثبيت التبعيات إذا لزم الأمر:

   npm install

3. ابدأ تطبيقك باستخدام الأمر التالي:

   npm start

4. افتح نافذة جديدة في جهازك الطرفي وابدأ تشغيل الخادم:

    npm run server
   

5. في المتصفح، انتقل إلى صفحة المنتج التي حددت فيها التطبيق ليظهر (على سبيل المثال، بطاقة الصفقة/العميل/جهة الاتصال) وألحق ?zcli_apps=true بعنوان URL. مثال:

   https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true

6. في شريط العناوين بالمتصفح الخاص بك، انقر فوق رمز الدرع الموجود على اليمين (Chrome) أو رمز القفل الموجود على اليسار (Firefox) ووافق على تحميل برنامج نصي غير آمن (Chrome) أو تعطيل الحماية (Firefox).

   ملحوظة: لا يوجد لدى Safari خيار لتعطيل الحماية.

تشغيل الوبر

من أجل فحص بعض الأخطاء وإصلاحها تلقائيًا، قم بتشغيل:

npm run lint

تشغيل أجمل

من أجل تنسيق التعليمات البرمجية الخاصة بك:

npm run prettier

بناء الرمز البريدي

بناء حزمة مع مصادر مصغرة:

npm run build

يقوم الأمر بإنشاء ملف .zip جديد في dist/tmp . الآن أصبح تطبيقك جاهزًا للتثبيت كتطبيق خاص في Zendesk Sell!

تثبيت تطبيق خاص في Zendesk Sell

1. انتقل إلى إعدادات Zendesk Sell الخاصة بك.
2. ابحث عن قسم Integrations ثم حدد علامة التبويب Apps .
3. انقر فوق الزر Upload private app .
4. قم بتسمية تطبيقك وقم بتحميل أحدث ملف بتنسيق .zip من dist/tmp في مشروع التطبيق المحلي الخاص بك.
5. قم بتثبيت التطبيق.

اختبار تطبيق باستخدام OAuth أو الإعدادات الآمنة محليًا

إذا كان تطبيقك يستخدم OAuth أو إعدادات آمنة، فيمكنك الاستمرار في اختباره محليًا بعد تثبيته عن بُعد.

1. قم بتثبيت التطبيق كتطبيق خاص في Zendesk Sell. راجع تثبيت تطبيق خاص في Zendesk Sell
2. انتقل إلى المجلد الجذر للتطبيق وقم بإنشاء ملف باسم zcli.apps.config.json
3. الصق المحتوى أدناه (ملاحظة: يمكنك أيضًا تعديل مفاتيح plan paramters ).

{
    "plan" : " silver " ,
    "app_id" : YOUR_APP_ID,
    "parameters" : {}
}

للعثور على معرف تثبيت التطبيق، قم بتسجيل الدخول إلى مثيل Zendesk Sell الخاص بك كمسؤول وافتح الصفحة التالية في نفس المتصفح، مع استبدال your_subdomain بالنطاق الخاص بك:

https://your_subdomain.zendesk.com/api/sell/apps/installations.json (عند الإنتاج)

حدد موقع التطبيق المثبت لديك ولاحظ قيمة id الخاص به، وليس قيمة app_id الخاصة به.

3. اختبر التطبيق بشكل طبيعي مع الخادم المحلي. راجع اختبار التطبيق محليًا.