פיתוח ווידג'טים ל-Bitrix24: מבדיקה ועד השקה

פיתוח וידג'טים ל-Bitrix24: מבדיקת נאותות ועד פריסה

תרחיש קלאסי: ה-CRM כבר בשימוש, מנהלים מטפלים בכל העסקאות, אבל צריך להוסיף בלוק בכרטיס העסקה עם נתונים ממערכת חיצונית—למשל, מלאי מחסן מה-ERP או סטטוס משלוח מחברת הובלה. כלים סטנדרטיים לא יספיקו; צריך וידג'ט דרך REST API ומנגנון ההטמעה של UI Extensions. אנחנו בחברה שלנו פותרים משימות כאלה באופן קבוע: אינטגרציית ERP, סנכרון סטטוסי משלוח, הצגת קבלות פיסקליות מ-OFD ישירות בכרטיס הליד. במהלך השנים פיתחנו גישה ברורה לפיתוח וידג'טים: מבדיקת תהליכים עסקיים ועד פרסום ב-Marketplace. במאמר זה, אנו חולקים תובנות מעשיות.

וידג'טים ב-Bitrix24 הם סוג נפרד של אפליקציה שמוצגת בתוך ממשק הפורטל באמצעות iframe או JS SDK. בגרסאות פורטל עדכניות, Bitrix מפתחת באופן פעיל את הקונספט של UI Extensions כחלופה יעילה ונוחה יותר לוידג'טים קלאסיים של iframe. בואו נפרק מה לבחור למשימה ספציפית ואיך הכל עובד מתחת למכסה המנוע.

איך לבחור בין iframe ל-UI Extensions?

אילו סוגי וידג'טים ומקומות הטמעה קיימים?

Bitrix24 תומך במספר מנגנוני הטמעה:

• Placement API (BX24.placement.call) — הדרך הקלאסית: האפליקציה רושמת placement, Bitrix24 מציגה אותו במיקום המתאים בממשק.
• UI Extensions — סט של רכיבים מוכנים (Button, Dialog, Loader, Alert) הזמינים דרך @bitrix24/b24jssdk.
• Slider — פתיחת כתובת URL שרירותית בפאנל צדדי דרך BX24.openApplication().

ה-placements הנוכחיים נרשמים במהלך התקנת האפליקציה דרך שיטת app.option.set ונשמרים בטבלת b_app_option. רשימת נקודות הטמעה זמינות:

כל placement מעביר מידע קונטקסטואלי לוידג'ט: מזהה ישות, סוג, זכויות גישה. מידע נוסף על placements ניתן למצוא בתיעוד הרשמי.

איך עובד וידג'ט iframe?

וידג'ט טיפוסי מורכב משני חלקים: handler בצד השרת (endpoint שמחזיר את HTML של דף הווידג'ט) וקוד לקוח בתוך ה-iframe.

אתחול בקוד הלקוח:

BX24.init(() => {
    const placement = BX24.placement.info();
    const dealId = placement.options.ID;
    BX24.callMethod('crm.deal.get', { id: dealId }, (result) => {
        if (result.error()) {
            console.error(result.error());
            return;
        }
        renderWidget(result.data());
    });
});

גובה ה-iframe הוא בעיה נפוצה. Bitrix24 לא הופכת את ה-iframe לאלסטי אוטומטית. לאחר עיבוד התוכן, יש לקרוא במפורש:

BX24.fitWindow(() => { // callback после изменения высоты }); 

אם לא עושים זאת, הווידג'ט ייחתך או שיופיע פס גלילה פנימי.

למה UI Extensions מהירים יותר?

בגרסאות פורטל עדכניות, מומלץ להשתמש ב-BX24.init(() => { const placement = BX24.placement.info(); const dealId = placement.options.ID; BX24.callMethod('crm.deal.get', { id: dealId }, (result) => { if (result.error()) { console.error(result.error()); return; } renderWidget(result.data()); }); }); . הוא מספק גישה טיפוסית ל-REST API ישירות מה-iframe:

import { initializeB24Frame, B24Frame } from '@bitrix24/b24jssdk';

const $b24 = await initializeB24Frame();
const profile = await $b24.fetchProfile();
const result = await $b24.callMethod('crm.deal.list', {
  filter: { ASSIGNED_BY_ID: profile.id },
  select: ['ID', 'TITLE', 'STAGE_ID']
});

ה-SDK מטפל באימות (טוקן OAuth מועבר אוטומטית דרך postMessage), אין צורך לאחסן BX24.fitWindow(() => { // callback после изменения высоты }); בצד הלקוח. UI Extensions מתחיל 30% מהר יותר מוידג'ט iframe בזכות אירועים ישירים.

רישום Placement ומניפסט אפליקציה

האפליקציה רושמת placements במהלך ההתקנה דרך ה-hook @bitrix24/b24jssdk. דוגמה במניפסט:

{
  "placements": [
    {
      "placement": "CRM_DEAL_DETAIL_TAB",
      "handler": "https://myapp.example.com/widget/deal-tab",
      "title": "Данные ERP",
      "description": "Остатки и резервы по позициям сделки"
    }
  ]
}

או פרוגרמטית דרך REST:

POST /rest/placement.bind
{
  "PLACEMENT": "CRM_DEAL_DETAIL_TAB",
  "HANDLER": "https://myapp.example.com/widget/deal-tab",
  "TITLE": "Склад"
}

למה אבטחת OAuth חשובה?

כל הבקשות מה-iframe לשרת חייבות לעבור דרך import { initializeB24Frame, B24Frame } from '@bitrix24/b24jssdk'; const $b24 = await initializeB24Frame(); const profile = await $b24.fetchProfile(); const result = await $b24.callMethod('crm.deal.list', { filter: { ASSIGNED_BY_ID: profile.id }, select: ['ID', 'TITLE', 'STAGE_ID'] }); (טוקן קצר מועד, שעה אחת) או להשתמש ב-client_secret כדי לחדש אותו. לעולם אל תאחסן OnAppInstall בקוד הלקוח—רק בשרת.

אמת { "placements": [ { "placement": "CRM_DEAL_DETAIL_TAB", "handler": "https://myapp.example.com/widget/deal-tab", "title": "Данные ERP", "description": "Остатки и резервы по позициям сделки" } ] } נכנסים מ-POST /rest/placement.bind { "PLACEMENT": "CRM_DEAL_DETAIL_TAB", "HANDLER": "https://myapp.example.com/widget/deal-tab", "TITLE": "Склад" } :

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://your-portal.bitrix24.ru') return;
  // обработка
});

OAuth הוא מרכיב אבטחה מרכזי. הניסיון מראה שרוב שגיאות פיתוח הווידג'טים קשורות לטיפול לא נכון בטוקנים. מידע נוסף על OAuth ניתן למצוא בויקיפדיה.

טעויות נפוצות והפתרונות שלהן

• מדיניות אבטחת תוכן (CSP) של Bitrix24 מגבילה AUTH_ID. דומיין האפליקציה שלך חייב להיות ברשימה הלבנה, מה שמוגדר אוטומטית בעת פרסום ב-Marketplace או רישום אפליקציה מקומית.
• אתחול איטי של BX24.init() — אם הווידג'ט נטען יותר מ-3 שניות, משתמשים עוברים לטאב אחר. אופטימיזציה: טען bx24.js דרך CDN, הצג skeleton loader עד שהנתונים מגיעים.
• עוגיות חוצות דומיינים — לאימות סשן של ה-backend שלך, השתמש ב-SameSite=None; Secure, אחרת הדפדפן חוסם עוגיות בתוך ה-iframe.

אם נתקלתם באחת מהבעיות הללו, צרו קשר. המומחים המוסמכים שלנו יעזרו לאבחן ולתקן את הבעיה. פנו אלינו ונשוב אליכם עם הערכת פרויקט.

מה כוללת העבודה

• בדיקת נאותות של ה-CRM הנוכחי ותרחישי אינטגרציה
• עיצוב ארכיטקטורת וידג'ט עם מחשבה על אבטחה
• יישום ובדיקות במספר דפדפנים (Chrome, Firefox, Safari, אפליקציות מובייל)
• אינטגרציה עם מערכות חיצוניות (ERP, OFD, חברות הובלה)
• תיעוד להתקנה ותחזוקה
• הכשרת מנהלי פורטל

אנו מספקים אחריות על כל העבודות שבוצעו. לכן, אנו משתמשים רק בפתרונות מוכחים ובניסיון של שנים.

לוח זמנים לפיתוח

הזמן העיקרי מושקע לא בווידג'ט עצמו, אלא בהגדרת אימות OAuth, טיפול במקרי קצה (טוקן שפג תוקפו, פורטל במרכז נתונים אחר), ובדיקות במספר דפדפנים—Bitrix24 תומך ב-Chrome, Firefox, Safari, ואפליקציות מובייל עם התנהגות iframe שונה.

הזמינו פיתוח וידג'ט עוד היום. נעריך את הפרויקט שלכם. צרו קשר כדי לדון בפרטים.