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

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

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

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

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

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

התקנת ה-SDK של Headless Web

כדי להתקין את לקוח ה-SDK של Headless Web, משתמשים בקטע הקוד הבא בפרויקט.

אפשר להתקין את החבילה באמצעות npm:

npm install @ujet/websdk-headless --save

אפשר גם להשתמש בסקריפט שמתארח ב-UJET:

<script src="https://websdk.ujet.co/v3/headless.js"></script>

<script>
  // The hosted script exposes the client as the global `UJETClient`.
  // const client = new UJETClient(...)
</script>

שימוש ב-SDK לאינטרנט ללא ממשק משתמש (headless)

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

import { Client } from "@ujet/websdk-headless"

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()

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

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

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

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

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

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

אתם יכולים להפעיל ולהגדיר את שיתוף המסך באמצעות ה-SDK של Headless Web.

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

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

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

interface CobrowseOption {
  enabled?: boolean
  // Widget-only - the following template + root options have no effect in the Headless SDK:
  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[]
  // Headless consent callbacks
  confirmSession?: () => Promise<boolean>
  confirmRemoteControl?: () => Promise<boolean>
  confirmFullDevice?: () => Promise<boolean>

  // Headless session-control callbacks
  showSessionControls?: () => void
  hideSessionControls?: () => void

  // Existing CobrowseIO instance
  instance?: any
}

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

אפשר להתאים אישית את התבנית של תיבת הדו-שיח של שיתוף המסך באמצעות האפשרות 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"
}

Headless client API

import { Client } from "@ujet/websdk-headless"

אירועים

רשימה של כל האירועים שנשלחים מופיעה בדף אירועים.

מאפיינים

שם תיאור
deviceId מזהה המכשיר, שנקבע על ידי ה-SDK ללא ממשק משתמש בזמן האתחול.
lang הגדרת השפה הנוכחית של הלקוח. אם השפה מועברת בהגדרות, היא הופכת לקריאה בלבד.
chat יש ערך רק כשיש שיחה פעילה.
cobrowse לקוח CobrowseIO הבסיסי, שזמין אחרי שהתחילה הגלישה המשותפת

אירועים

רשימה של כל האירועים שנשלחים מופיעה בדף כל האירועים הזמינים.

שם תיאור
destroy הורס את ה-communicator ואת כל רכיבי ה-event listener.
on מוסיפה גורם מטפל באירועים לאירוע שצוין.
off הסרת הגורם המטפל באירועים שצוינו.

משתמשים ב-method‏ .destroy כדי להסיר את ה-iframe ואת כל רכיבי ה-event listener:

client.destroy()

משתמשים ב-method‏ .on כדי לעקוב אחרי האירועים:

client.on('chat.updated', someFunc)

מסירים את הגורם המטפל באירועים באמצעות .off:

client.off('chat.updated', someFunc)

הטמעה של קובץ עזר

ב-GitHub יש ccaas-web-headless-sdk-sample.

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