מדריך ל-SDK של Headless web

‫Web SDK ללא ראש מאפשר לכם להרחיב ולהתאים אישית את חוויית התמיכה של החברה בהתאם לצרכים שלכם. היא כוללת את כל התכונות המוכרות של Web SDK ומאפשרת לפתח את ממשק המשתמש וחוויית המשתמש כדי לתמוך בהן.

כדי להתקין ולהשתמש ב-SDK של headless web, צריך את התמיכה של צוות פיתוח האתרים בארגון. כדי לבצע שילוב מוצלח ולהשיג ביצועים אופטימליים, Google ממליצה לערב את אנשי הצוות המוסמכים שלכם.

בהקשר של פיתוח תוכנה, המונח 'חסר ראש' מתייחס לארכיטקטורה מנותקת שבה שכבת ההצגה של ממשק המשתמש (ה'ראש') מופרדת מהלוגיקה ומהיכולות של העורף. בארכיטקטורה ללא ממשק משתמש, ה-Backend, שנקרא גם החלק 'ללא ממשק משתמש', מספק ממשקי API שמאפשרים להשתמש בתכונות ובשירותים שלו.

דוגמה לכך היא אוטומציה של תהליכי עבודה בהתאמה אישית. כשמשתמש קצה מתחיל צ'אט, מופעל האירוע on("chat.message"). אתם יכולים להגדיר טריגרים מותאמים אישית לאוטומציה על סמך הודעות צ'אט ספציפיות שקיבלתם. לדוגמה, אם משתמש קצה מקליד 'העברה לטיפול ברמה גבוהה יותר' בצ'אט, אפשר להגדיר את המטפל באירועים כך שיעביר אוטומטית את סשן הצ'אט לצוות תמיכה ברמה גבוהה יותר, כדי לטפל בבעיות קריטיות במהירות.

במדריך הזה מוסבר איך להתקין את ה-SDK, איך לשלב אותו ואיך להשתמש בו. פרטים על השימוש ב-API זמינים במסמכי התיעוד של Headless web SDK API. רשימה של האירועים הזמינים מופיעה בדף האירועים.

התקנה של SDK לאינטרנט ללא ממשק משתמש

כדי להתקין את headless web SDK, משתמשים בקטע הקוד הבא בפרויקט:

npm install @ujet/websdk-headless --save

שימוש ב-SDK לאינטרנט ללא GUI

כדי להשתמש ב-Web SDK ללא ראש, אפשר לפעול לפי קוד הדוגמה שמופיע כאן:

import { Client } from "@ujet/websdk-headless"
const client = new Client({ ... })

async function authenticate() {
  const resp = await fetch("/your-auth-endpoint")
  const data = await resp.json()
  return { token: data.token }
}

const client = new Client({
  companyId: "YOUR-COMPANY-ID",
  tenant: "YOUR-TENANT-NAME",
  authenticate: authenticate,
})

// const company = await client.getCompany()
// const menus = await client.getMenus()

מחלקת הלקוח מקבלת כמה אפשרויות (אפשר להתאים אישית לפי הדרישות שלכם):

interface ClientOption {
  companyId: string;
  authenticate: () => Promise<TokenResponse>;
  tenant?: string;
  host?: string;
  lang?: string;
  bridge?: string;
  cobrowse?: {
    enabled: boolean;
    messages?: CobrowseMessages;
    api?: string;
    license?: string;
    trustedOrigins?: string[];
    capabilities?: string[];
    registration?: boolean;
    redactedViews?: string[];
    unredactedViews?: string[];
  };
}

הפעלת רישום ביומן

במהלך ההטמעה והבדיקה, יכול להיות שיהיה צורך לאסוף מידע נוסף ביומן המסוף. כדי להפעיל את הרישום ביומן עבור ה-SDK ללא ראש, צריך לייבא את Logger ואת consoleLoggerHandler על ידי הוספת הקוד הבא לאפליקציית האינטרנט:

import {Logger, consoleLoggerHandler } from '@ujet/websdk-headless'
Logger.addHandler(consoleLoggerHandler)

הגדרת שיתוף המסך

אפשר להפעיל ולהגדיר את שיתוף המסך באמצעות headless web SDK.

בדוגמת הקוד הבאה אפשר לראות איך מפעילים את שיתוף המסך:

new Client({
  // ...
  cobrowse: {
    enabled: true,
    license: 'YOUR_SCREEN_SHARE_LICENSE'
  }
})

בדוגמת הקוד הבאה אפשר לראות את האפשרויות לשיתוף המסך:

interface CobrowseOption {
  enabled: boolean
  template?: string
  confirmSessionTemplate?: string
  confirmRemoteControlTemplate?: string
  confirmFullDeviceTemplate?: string
  sessionControlsTemplate?: string
  root?: Element
  messages?: {
    confirmSessionTitle: string;
    confirmSessionContent: string;
    confirmRemoteControlTitle: string;
    confirmRemoteControlContent: string;
    confirmFullDeviceTitle: string;
    confirmFullDeviceContent: string;
    allowText: string;
    denyText: string;
    endSessionText: string;
  }
  api?: string
  license?: string
  trustedOrigins?: string[]
  capabilities?: string[]
  registration?: boolean
  redactedViews?: string[]
  unredactedViews?: string[]
}

תבנית מותאמת אישית

אפשר להתאים אישית את תבנית תיבת הדו-שיח של שיתוף המסך באמצעות האפשרות template שמופיעה בקוד לדוגמה שלמעלה.

בדוגמה הבאה מוצגת תבנית ברירת המחדל:

<dialog open class="cobrowse-dialog">
  <h1>$title</h1>
  <div class="cobrowse-dialog_content">$content</div>
  <div class="cobrowse-dialog_footer">
    <button class="cobrowse-dialog_allow js-cobrowse-allow">$allow</button>
    <button class="cobrowse-dialog_deny js-cobrowse-deny">$deny</button>
  </div>
</dialog>

אתם יכולים להשתמש בתבנית הזו כדי להגדיר תיבת דו-שיח שמבקשת אישור ממשתמש הקצה לפעולות הבאות:

  • איך מתחילים סשן של שיתוף מסך

  • התחלת סשן של שיתוף מסך עם שליטה מרחוק

  • התחלת סשן של שיתוף מסך של המכשיר כולו

אלה אפשרויות התבניות:

  • ‫confirmSessionTemplate: לאישור של סשן שיתוף מסך.

  • ‫confirmRemoteControlTemplate: לאישור של הפעלת שיתוף מסך בשלט רחוק.

  • ‫confirmFullDeviceTemplate. כדי לאשר הפעלה של שיתוף מסך של המכשיר כולו.

  • ‫sessionControlsTemplate: לכפתור של אמצעי הבקרה על הפעילות. זוהי תבנית ברירת המחדל: <button class="cobrowse-end js-cobrowse-end">$end</button>

Messages

משתני ההודעה הבאים משמשים בתבניות בהתאמה אישית:

  • $title

  • $content

  • $allow

  • $deny

בדוגמה הבאה אפשר לראות איך המשתנים האלה מיושמים:

{
  confirmSessionTitle: string;  // $title
  confirmSessionContent: string;  // $content
  confirmRemoteControlTitle: string;  // $title
  confirmRemoteControlContent: string;  // $content
  confirmFullDeviceTitle: string;  // $title
  confirmFullDeviceContent: string;  // $content
  allowText: string;  // $allow
  denyText: string;  // $deny
  endSessionText: string;  // $end
}

בדוגמה הבאה מוצגים ערכי ברירת המחדל של המשתנים באנגלית:

{
  "confirmSessionTitle": "Screen Share Session Request",
  "confirmSessionContent": "Do you want to share your current screen with the agent?",
  "endSessionText": "End Screen Share Session",
  "confirmRemoteControlTitle": "Remote Access Request",
  "confirmRemoteControlContent": "The agent would like to have access to your currently shared screen to further assist you. Do you want to allow this?",
  "confirmFullDeviceTitle": "Screen Share Request",
  "confirmFullDeviceContent": "Do you want to share your full screen with the agent? The agent will not be able to control anything on the screen.",
  "allowText": "Allow",
  "denyText": "Deny"
}

הגדרת נתונים בהתאמה אישית

האפשרות custom_data מאפשרת להעביר נתונים של צמדי מפתח/ערך שרירותיים אל ה-SDK לאתרים.

שימוש

כשיוצרים צ'אט, אפשר לספק נתונים בהתאמה אישית כאובייקט (לא חתום) או כמחרוזת (חתום):

interface ChatRequest {
  lang?: string;
  trigger_id?: string;
  ticket_id?: string;
  email?: string;
  greeting?: string;
  cobrowsable?: boolean;
  custom_data?: {
    signed?: string;
    unsigned?: Record<string, any>;
  };
}

מקרה לדוגמה:

const custom_data = {
  unsigned: {
    version: {
      label: 'Version',
      value: '1.0.0'
    }
  },
  signed: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' // JWT or other signed payload
}

try {
  const chat: Chat = await client.createChat(123, { custom_data })
} catch (error) {
  // handle error
}

העברה של צ'אטבוט חיצוני

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

מקרה לדוגמה:

const custom_data = {
  unsigned: {
    external_chat_transfer: {
      greeting_override: "Please hold while we connect you with a human agent.",
      agent: {
        name: "Agent Name",
        avatar: "https://ujet.s3.amazonaws.com/default-virtual-agent-avatar-1.png"
      },
      transcript: [
        {
          sender: "agent",
          timestamp: "2021-03-15 12:00:00Z",
          content: [
            {
              type: "text",
              text: "Hello! How can I help you today?"
            },
            {
              type: "buttons",
              buttons: [
                {
                  label: "Create New Order",
                  selected: false
                },
                {
                  label: "Check Order Status",
                  selected: true
                },
                {
                  label: "Check Account Balance",
                  selected: false
                },
              ]
            }
          ]
        },
        {
          sender: "end_user",
          timestamp: "2021-03-15 12:00:15Z",
          content: [
            {
              type: "text",
              text: "Check Order Status"
            }
          ]
        },
        {
          sender: "agent",
          timestamp: "2021-03-15 12:00:16Z",
          content: [
            {
              type: "text",
              text: "I can help you with that, what's your order number?"
            }
          ]
        },
        {
          sender: "end_user",
          timestamp: "2021-03-15 12:00:20Z",
          content: [
            {
              type: "media",
              media: {
                type: "image",
                url: "https://ujet.s3.amazonaws.com/default-virtual-agent-avatar-1.png"
              }
            }
          ]
        }
      ]
    }
  },
  signed: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' // JWT or other signed payload
}

try {
  const chat: Chat = await client.createChat(123, { custom_data })
} catch (error) {
  // handle error
}

הטמעה לדוגמה

למידע על הטמעה לדוגמה של ה-SDK לאינטרנט, אפשר לעיין ב-ccaas-web-headless-sdk-sample ב-GitHub.

המאגר הזה מכיל הדגמה של אפליקציית צ'אט שנבנתה באמצעות CCAI Platform Web Headless SDK. הוא מציג ארכיטקטורה בסיסית של לקוח-שרת שבה קצה העורפי (backend) של Node.js מטפל באימות מאובטח ובמסירת הגדרות, בעוד שהקצה הקדמי (frontend) של JavaScript טהור מספק את ממשק המשתמש של הצ'אט.