تكوين التطبيق

​

نظرة عامة

• الهوية — المعرّف الشامل، واسم العرض، والوصف.
• الأذونات — الدور الذي تعمل بموجبه دوال المنطق والمكوّنات الأمامية الخاصة به.
• إمكانات الوسائط (اختياري): الوصول إلى الميكروفون أو الكاميرا الذي تطلبه مكوّنات الواجهة، ويُوافق عليه بشكل منفصل عن أذونات الدور.
• المتغيرات (اختياري) — أزواج مفتاح–قيمة تُتاح لكودك كمتغيرات بيئة.
• خطافات ما قبل التثبيت/ما بعد التثبيت/إلغاء التثبيت (اختياري) — راجع Logic Functions.
• الفوترة (اختياري) — billing.recurring لرسوم الاشتراك التي تفرضها المنصة تلقائيًا، وbilling.operations لما تفرض عليه تطبيقك أرصدة، وbilling.description للسوق؛ راجع فرض الأرصدة.

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'My Twenty App',
  description: 'My first Twenty app',
  applicationVariables: {
    DEFAULT_RECIPIENT_NAME: {
      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
      label: 'Default recipient name',
      description: 'Default recipient name for postcards',
      value: 'Jane Doe',
      isSecret: false,
    },
    API_KEY: {
      universalIdentifier: '6b1f5a02-7c4d-4a19-9e63-2f0c8a5d1b47',
      label: 'API key',
      description: 'Key used to reach the postcard provider',
      isSecret: true,
      isRequired: true,
    },
  },
});

• حقول universalIdentifier هي UUID تنشئها مرة واحدة وتملكها. أبقِها ثابتة عبر عمليات المزامنة. يجب أن يكون universalIdentifier الخاص بالتطبيق UUID صالحًا: يرفض الخادم بيانًا يكون معرّفه ليس UUID صالحًا. إنه فريد عبر النسخة بأكملها ومرتبط بمساحة العمل التي تملك تسجيله، لذا لا يمكن مزامنة التطبيق إلا لمساحة العمل تلك — راجع ملكية التسجيل.
• تقبل applicationVariables قيمة label اختيارية — اسمًا سهل الاستخدام يُعرض في صفحة إعدادات التطبيق بدلًا من مفتاح المتغير الخام.
• applicationVariables تصبح متغيرات بيئة لوظائفك ومكوّناتك الأمامية. في وظائف المنطق (على جانب الخادم)، تكون متاحة على شكل process.env.VARIABLE_NAME. في المكوّنات الأمامية، استخدم getApplicationVariable('VARIABLE_NAME') من twenty-sdk/front-component. يتم حقن المتغيّرات المعلَّمة بـ isSecret: true في وظائف المنطق فقط. المكوّنات الأمامية تتلقّى المتغيّرات غير السرّية فقط. يحتفظ متغير ذو scope: 'USER' بقيمة العضو الذي يعمل الكود لصالحه: راجع متغيرات مساحة العمل والمستخدم.
• يمكن لتطبيقك أيضًا قراءة قيم متغيراته وتحديثها في وقت التشغيل، وهي الطريقة التي يحفظ بها مكوّن الإعدادات المخصص ما كتبه المستخدم: راجع قراءة المتغيرات وتحديثها في وقت التشغيل. لا يصل التطبيق مطلقًا إلا إلى متغيراته الخاصة، ضمن مساحة العمل الخاصة به.
• يتم اكتشاف الدور الافتراضي تلقائيًا من ملف الدور المميز بـ defineApplicationRole() — لست بحاجة إلى الإشارة إليه من defineApplication().
• يتم اكتشاف دوال ما قبل التثبيت وما بعد التثبيت وإلغاء التثبيت، وفحوصات السلامة، تلقائيًا أثناء بناء البيان — لا حاجة للإشارة إليها في defineApplication().
• لا يزال تمرير defaultRoleUniversalIdentifier بشكل صريح مدعومًا من أجل التوافق مع الإصدارات السابقة، ولكنه مُهمل لصالح defineApplicationRole().
• serverVariables هي تكوينات وأسرار بنطاق المثيل (مثل مفاتيح واجهة برمجة التطبيقات). على عكس applicationVariables، فهي لا تصرح عن أي قيمة في ملف manifest — حيث يقوم مشغّل مساحة العمل بملئها من إعدادات التطبيق، ويتم حقنها في دوال المنطق فقط بعد تعيينها.
• يمكن للتطبيق الإبلاغ عن حالة تهيئته الخاصة باستخدام defineHealthCheck()، وذلك للأمور التي لا يعرفها إلا التطبيق نفسه — مفتاح موجود لكنه مُلغى، أو حساب تابع لجهة خارجية على الخطة الخاطئة. يغطي isRequired ما يمكن لـ Twenty رؤيته بمفرده؛ بينما يغطي فحص السلامة الباقي. عيّن runOnUserPreferences: true للتحقق من إعداد كل عضو على صفحة تفضيلات التطبيقات الخاصة به بدلًا من إعدادات تطبيق مساحة العمل. يؤدي حذف الخيار أو تعيينه إلى false إلى الإبقاء على فحص مساحة العمل الحالي.
• يقبل كلا نوعي المتغير ‎isRequired: true‎. إذا لم تُدخل مساحة العمل قيمة متغير مطلوب بعد، فسيظل التطبيق غير مُهيأ: تعرض صفحة إعداداته لافتةً تسمي المتغيرات المفقودة، مع زر ينتقل إلى علامة التبويب حيث تُضبط هذه المتغيرات. ضع علامة «مطلوب» فقط على ما لا يمكن للتطبيق تشغيله فعليًا بدونه — يجب أن يظل المتغير الاختياري ذو القيمة الافتراضية المعقولة اختياريًا.
• كلا نوعي المتغير يقبلان ‎isDeprecated: true‎. استخدم ذلك لإيقاف استخدام متغير بدلاً من حذفه: إبقاء المفتاح معلناً يحافظ على القيمة المخزنة (حذفه يدمّر القيمة التي أدخلها المشغّل)، ولا يزال يتم حقن المتغير، بحيث يمكن لشفرتك أن تعتمد عليه كخيار احتياطي — ‎process.env.NEW_API_KEY ?? process.env.API_KEY‎. يختفي المتغير المهمل من إعدادات التطبيق عند عدم تحديد قيمة له، ولا يؤخذ في الحسبان ضمن فحص تهيئة التطبيق، لذا تكون isDeprecated أعلى أولوية من isRequired.
• يُعيّن Twenty هذه الأسماء لكل تشغيل لدالة منطقية، لذا فهي محجوزة: TWENTY_API_URL، TWENTY_APP_ACCESS_TOKEN، TWENTY_APP_APPLICATION_ACCESS_TOKEN، TWENTY_API_KEY، TWENTY_FUNCTIONS_URL، TWENTY_SERVER_ROUTES_URL وAPPLICATION_ID. يُحجز أيضًا كل اسم آخر يبدأ بـ TWENTY_ للمتغيرات التي يضيفها Twenty لاحقًا. يُرفض البيان الذي يعلن اسمًا محجوزًا كمتغير للتطبيق أو الخادم عند مزامنة التطبيق أو نشره.
• لإضافة إدخالاتك الخاصة إلى قائمة إعدادات التطبيق (بدلًا من صفحة Variables المُنشأة)، صرّح بمكوّن واجهة أمامية ووجّه defineSettingsMenuItem() إليه، في ملفه الخاص. صرّح بعدد ما تحتاج إليه ورتّبها باستخدام position؛ يضع scope عنصرًا ضمن إعدادات مساحة العمل أو ضمن إعدادات كل عضو الخاصة. يأتي عنصر عام الذي يديره النظام (الترقية التلقائية، عنوان URL للتطبيق، الاتصالات) دائمًا أولًا، ولا يظهر عنوان URL للتطبيق إلا عندما يحتوي التطبيق على وظائف يتم تشغيلها عبر HTTP.

​

إمكانات الوسائط المطلوبة

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'Media recorder',
  description: 'Record audio and video in your workspace',
  requestedCapabilities: ['microphone', 'camera'],
});

​

الوصول إلى وسائط موقع الويب المضمّن

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'Phone',
  description: 'Call your contacts from Twenty',
  requestedIframeMediaPermissions: [
    { origin: 'https://workspace.aircall.io', microphone: true, camera: false },
  ],
});

​

أنواع المتغيرات

import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    MAX_POSTCARDS: {
      universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
      description: 'Maximum postcards per batch',
      type: FieldType.NUMBER,
      value: 10,
    },
    DEFAULT_REGION: {
      universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
      description: 'Default shipping region',
      type: FieldType.SELECT,
      options: [
        { label: 'Europe', value: 'eu' },
        { label: 'United States', value: 'us' },
      ],
      value: 'eu',
    },
  },
});

const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }

​

متغيرات مساحة العمل والمستخدم

• WORKSPACE (افتراضي): قيمة واحدة لمساحة العمل بأكملها، يعيّنها عضو يمكنه إدارة التطبيقات.
• USER: يحتفظ كل عضو بقيمته الخاصة.

import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    RECORD_MY_MEETINGS: {
      universalIdentifier: '0b6f3c1e-8a2d-4f57-9c1b-7e4d2a9f6c30',
      label: 'Record my meetings',
      type: FieldType.BOOLEAN,
      value: true,
      scope: 'USER',
    },
  },
});

• في دالة منطقية، يحتوي process.env على قيم العضو الذي شغّل التنفيذ، وهو العضو نفسه الذي يعمل TWENTY_APP_ACCESS_TOKEN بصفته. لا يحصل تنفيذ لا يقف وراءه أي شخص، مثل مهمة cron أو خطاف تثبيت، على أي متغيرات مستخدم على الإطلاق.
• في مكوّن واجهة، تُرجع getApplicationVariable قيم العضو الذي يعرضه. تُستبعد متغيرات المستخدم السرية، مثل متغيرات مساحة العمل السرية.

import { MetadataApiClient } from 'twenty-client-sdk/metadata';

// In a logic function, for example a cron job
const client = new MetadataApiClient({ runAs: 'application' });

const { myUserApplicationVariables } = await client.query({
  myUserApplicationVariables: {
    workspaceMemberId: true,
    variables: { key: true, value: true },
  },
});

​

الدور الافتراضي للوظيفة

• رموز وقت التشغيل المحقونة في دوال المنطق لديك مستمدة من هذا الدور. تُقيَّد المكالمة التي تتصرف كشخص بشكل أكبر بما يمكن لذلك الشخص القيام به، لذا لا يمكنها أبدًا تجاوز أيٍّ منهما. راجع صلاحيات الوصول التي تستخدمها المكالمة.
• يكون عميل واجهة برمجة التطبيقات مضبوط الأنواع مقيّدًا بالأذونات الممنوحة لذلك الدور.
• اتبع مبدأ أقل امتياز: صرّح فقط عن الأذونات التي تحتاجها دوالك.

​

بيانات التعريف لسوق التطبيقات