‫Headless Mobile SDK ל-iOS: שיחות קוליות, שיתוף מסך, שיחות מתוזמנות ואימייל

במאמר הזה מוסבר איך לשלב ולהתאים אישית את Headless Mobile SDK באפליקציה ל-Android. הוא כולל שיחות קוליות דרך CCAICall

שיחות קוליות

‫Headless Mobile SDK ל-iOS מספק תמיכה בשיחות קוליות דרך מודול CCAICall. האפליקציה שלכם היא הבעלים של ממשק המשתמש המותאם אישית לשיחות, בעוד ש-SDK מטפל בחיבור לשיחה, בשילוב עם CallKit, בטיפול בהתראות פוש של VoIP ובאירועים של מחזור החיים של השיחה.

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

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

הפעלת מודול השיחות

מאתחלים את מודול השיחות אחרי שמאתחלים את ה-SDK המרכזי:

import CCAIKit
import CCAICall

try CCAI.shared.initialize(options: options)
CCAI.shared.initializeCall(CallOptions())

בדיקת היכולות של VoiceCallChannel

לפני שמציעים שיחה מיידית, בודקים את מבנה הנתונים VoiceCallChannel של התור כדי להחליט אילו נקודות כניסה להציג (שיחה מיידית, מעבר אוטומטי לתא קולי, הפניית שיחה ברמת הערוץ) והאם נדרשת הסכמה להקלטה.

שדות מפתח VoiceCallChannel

  • ‫instantEnabled: Bool? – האם מותר לבצע שיחת טלפון בשידור חי (מיידי) בתור הזה. התייחסו אל nil או אל false כמצב "don't offer an instant call button". שונה מ-voiceCall != nil, שרק מציין אם יש בערוץ ההמתנה ערוץ קולי.

  • ‫preSessionSmartAction: Bool? – האם נדרשות פעולות חכמות לפני הפגישה בערוץ הספציפי הזה לפני שמתחילים שיחה. במאמר Headless Mobile SDK for iOS: Smart actions, attachments, and deflection מוסבר על הנתיב המשלים ברמת התור.

  • ‫scheduleEnabled: Bool? – האם יש תמיכה בשיחות מתוזמנות. במאמר שיחות מתוזמנות מוסבר על המסלול המשלים ברמת התור.

  • ‫recordingOption: RecordingOption? – מודל ההסכמה להקלטת שיחות (ראו הסכמה להקלטה). שונה מ-RecordingPermission.notAsked, שהוא ספציפי לתזמון.

  • ‫voicemailReason: String? – מאוכלס כשהערוץ מוגדר להעברה לתא הקולי.

  • ‫phoneNumber: String? – מספר חלופי ב-PSTN שהוגדר להעברת שיחה או להשארת הודעה קולית.

  • ‫scheduleDeflectionType: String? / deflected: Bool? / deflectedReason: String? – מטא-נתונים של הפניית שיחות ברמת הערוץ. כשמשתמש מנסה להתקשר למספר טלפון שלא הוגדר, במקום לנסות להתקשר באופן מיידי, המערכת מציגה את ההודעה deflected == true, show the admin-configured deflectedReason ומציעה את חלופת ברירת המחדל שהוגדרה (לדוגמה, מספר טלפון לחיוג או נקודת כניסה לשיחה מתוזמנת). מידע על ניהול העברת שיחות ברמת התור זמין במאמר העברת שיחות (לאחר שעות הפעילות ומעבר לקיבולת).

func voiceEntryPoints(for menu: QueueMenu) {
    guard let voice = menu.channels?.voiceCall else {
        hideCallNowButton()
        hideVoicemailButton()
        return
    }

    // Instant call - only when explicitly enabled and not deflected
    callNowButton.isHidden = (voice.instantEnabled != true) || (voice.deflected == true)

    // Voicemail fallback
    if let number = voice.phoneNumber, voice.voicemailReason != nil {
        showVoicemailButton(number: number, reason: voice.voicemailReason)
    }

    // Channel-level deflection
    if voice.deflected == true {
        showChannelDeflection(reason: voice.deflectedReason)
    }
}

מה ה-SDK מספק: שדה recordingOption: RecordingOption? ב-VoiceCallChannel שמתאר את מודל ההסכמה להקלטת שיחות שאדמינים הגדירו בפורטל.

מה יוצרים: את בקשת ההסכמה (כשמשתמשים ב-.askUser) ואת לוגיקת ההסתעפות שמכבדת את הבחירה של האדמין.

public enum RecordingOption: String, Decodable {
    case always   // Calls are always recorded - surface a disclosure before connecting
    case never    // Calls are never recorded - no disclosure needed
    case askUser  // Prompt the user for consent before the call connects
}

func handleRecordingConsent(
    for voice: VoiceCallChannel,
    completion: @escaping (Bool) -> Void
) {
    switch voice.recordingOption {
    case .always:
        showRecordingDisclosure(message: "This call will be recorded.")
        completion(true)
    case .never, .none:
        completion(true)
    case .askUser:
        presentConsentPrompt { granted in
            completion(granted)
        }
    }
}

התחלת שיחה מיידית

לפני שמתחילים שיחה מיידית:

  1. בודקים את VoiceCallChannel של התור שנבחר.

  2. בודקים שהאפשרות לשיחות מיידיות מופעלת ושהשיחות לא מועברות.

  3. הטיפול בהסכמה להקלטה מתבצע בהתאם לrecordingOption של התור.

  4. שולחים בקשה להרשאת גישה למיקרופון.

  5. התקשרות אל startInstantCall

func initiateInstantCall(for menu: QueueMenu) async {
    guard let voice = menu.channels?.voiceCall,
          voice.instantEnabled == true,
          voice.deflected != true else {
        return
    }

    let recordingPermission = await resolveRecordingPermission(for: voice)
    guard await requestMicrophonePermission() else { return }

    do {
        try await CCAI.shared.callService?.startInstantCall(
            InstantCallRequest(
                menuId: menu.id,
                recordingPermission: recordingPermission
            )
        )
    } catch {
        showCallStartError(error)
    }
}

התבוננות במצב השיחה

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

CCAI.shared.callService?.stateChanged
    .receive(on: DispatchQueue.main)
    .sink { state in
        updateCallConnectionState(state)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.callReceived
    .receive(on: DispatchQueue.main)
    .sink { call in
        updateCallDetails(call)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.incomingCallEvent
    .receive(on: DispatchQueue.main)
    .sink { event in
        handleIncomingCallEvent(event)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.waitTimeUpdated
    .receive(on: DispatchQueue.main)
    .sink { waitTime in
        // The platform pushed a new estimated wait time for the active call.
        updateEstimatedWaitTime(waitTime)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.participantUpdated
    .receive(on: DispatchQueue.main)
    .sink { participant in
        // Agent assignment, transfer, or participant metadata changed.
        updateParticipantInfo(participant)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.interruptionDetected
    .receive(on: DispatchQueue.main)
    .sink { interruption in
        // A PSTN interruption (for example, an incoming cellular call)
        // has paused the active CCAI call. Surface a "call interrupted"
        // banner and offer a Resume action after the interruption ends.
        showInterruptionBanner(reason: interruption)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.deflectionOffered
    .receive(on: DispatchQueue.main)
    .sink { deflection in
        // The platform offered a wait-time deflection (for example, a
        // scheduled callback or PSTN fallback). Render the prompt and
        // honor the user's choice.
        presentWaitTimeDeflection(deflection)
    }
    .store(in: &cancellables)

המצב של הספק לעומת סטטוס השרת

‫stateChanged ו-callReceived.status הם אותות עצמאיים – צריך לקרוא אותם כעמודות ולא כשורות. ב-stateChanged של הספק מדווח על לחיצת היד של ה-VoIP המקומי, וב-callReceived.status בצד השרת מדווח על מחזור החיים של השיחה בפלטפורמה. הפעלת המתג מחובר והתחלת הטיימר של השיחה מתבצעות מ-callReceived.status ולא מ-stateChanged כשהוא מגיע ל-.connected.

אות מה נכלל בדיווח מה אפשר להסיק ממנו
‫stateChanged (ספק) העברת נתונים (handshake) ב-VoIP מקומי – .connecting, .connected (מקומי), .disconnected, .error(...). אופציונלי: אנימציית טעינה לפני שהסטטוס של השרת מגיע, לפני שהשגיאה מוצגת ולפני ניקוי הנתונים בסיום השיחה.
‫callReceived.status (שרת) מחזור החיים בצד השרת – .waiting, .connecting, .connected, .onHold, .interrupted, .ended. התחברות, התחלת טיימר השיחה, ממשק משתמש להקצאת סוכן, שכבות-על של העברה או הסלמה ורצף הפעולות לסיום השיחה.

סטטוס השיחה והמצבים בצד השרת

מה ה-SDK מספק: ספירה (enum) של CallStatus מונחית-שרת בכל מטען ייעודי (payload) של Call, שמתארת את המיקום של הקריאה במחזור החיים שלה (לדוגמה, connecting,‏ waiting,‏ connected,‏ onHold,‏ interrupted,‏ ended).

מה שיוצרים: המיפוי מ-CallStatus למצבים שגלויים ללקוחות במסך השיחה (צלצול, המתנה בתור, חיבור, המתנה, הפרעה, סיום).

דוגמה להטמעה

מפעילים את call.status מכל פליטה של callReceived ומעבדים את מצב ממשק המשתמש התואם.

func updateCallDetails(_ call: Call) {
    switch call.status {
    case .connecting:
        renderConnectingState()
    case .waiting:
        renderWaitingInQueueState(estimatedWait: call.estimatedWait)
    case .connected:
        renderConnectedState(agent: call.agent)
    case .onHold:
        renderOnHoldState()
    case .interrupted:
        renderInterruptedState()
    case .ended, .failed:
        renderEndedState(reason: call.endReason)
    @unknown default:
        break
    }
}

אמצעי בקרה במהלך השיחה (השתקה, רמקול, החזקה)

מה ה-SDK מספק: מאפיינים לקריאה בלבד ב-callService – isMuted,‏ isSpeakerEnabled, ‏ isOnHold – לצד הפעולות להחלפת כל מצב (setMuted, ‏ setSpeakerEnabled, ‏ setOnHold).

מה יוצרים: לחצני ההשתקה, הרמקול וההמתנה בממשק המשתמש בשיחה, שמחוברים לפעולות של ה-SDK ומשקפים את המצב הנוכחי.

דוגמה להטמעה

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

// Read current state
muteButton.isSelected = CCAI.shared.callService?.isMuted ?? false
speakerButton.isSelected = CCAI.shared.callService?.isSpeakerEnabled ?? false
holdButton.isSelected = CCAI.shared.callService?.isOnHold ?? false

// Toggle from your UI handlers
func onMuteTapped() {
    let next = !(CCAI.shared.callService?.isMuted ?? false)
    CCAI.shared.callService?.setMuted(next)
    muteButton.isSelected = next
}

func onSpeakerTapped() {
    let next = !(CCAI.shared.callService?.isSpeakerEnabled ?? false)
    CCAI.shared.callService?.setSpeakerEnabled(next)
    speakerButton.isSelected = next
}

func onHoldTapped() {
    let next = !(CCAI.shared.callService?.isOnHold ?? false)
    CCAI.shared.callService?.setOnHold(next)
    holdButton.isSelected = next
}

המשך שיחה פעילה אחרי הפרעה

כששיחה פעילה ב-CCAI מושהית בגלל הפרעה ברשת PSTN (למשל שיחה סלולרית נכנסת), ה-SDK שומר על הפעלת הסשן ושולח את interruptionDetected. אחרי שההפרעה מסתיימת, האפליקציה יכולה להמשיך את השיחה.

מה ה-SDK מספק: getLastCallInProgress() כדי לחפש שיחה בתהליך (כולל אחרי הפעלה מחדש של האפליקציה) וresumeCall(_:) כדי להחזיר אותה לחזית.

מה אתם יוצרים: מזמינוּת המשך השיחה בממשק המשתמש (בדרך כלל באנר או המשך אוטומטי אחרי שההפרעה מסתיימת) ואת הניווט חזרה למסך השיחה.

דוגמה להטמעה

מחפשים את השיחה הפעילה באמצעות getLastCallInProgress, ממשיכים אותה וחוזרים למסך השיחה.

func resumeIfInterrupted() async {
    guard let call = try? await CCAI.shared.callService?.getLastCallInProgress() else {
        return
    }
    do {
        try await CCAI.shared.callService?.resumeCall(call)
        navigateToCallScreen(call)
    } catch {
        showCallResumeError(error)
    }
}

העברה לטיפול ברמה גבוהה יותר מנציג וירטואלי

מה ה-SDK מספק: canEscalate(allowSkipVirtualAgent:) היא שיטה ב-CallResponse (המודל שנוצר על ידי callService.callReceived), ולא ב-callService עצמו. הפונקציה מחזירה ערך בוליאני שמציין אם השיחה הנוכחית עומדת בדרישות להעברה לנציג אנושי, על סמך הסטטוס הנוכחי של הסוכן הווירטואלי בשיחה.

מה יוצרים: שומרים את פליטת callReceived האחרונה בתור מצב "current call", ואז מקשרים את הנראות של הלחצן Talk to a person ל-currentCall?.canEscalate(...). הארגומנט allowSkipVirtualAgent הוא ערך של הגדרת תפריט שמאחזרים בנפרד מתגובת השיחה עצמה – אל תקודדו את true באופן קשיח בסביבת הייצור.

דוגמה להטמעה

שומרים את Call האחרון בנכס מאוחסן, ואז מפעילים עליו את canEscalate. פותרים את הבעיה allowSkipVirtualAgent בהגדרת התפריט.

// Held from the most recent `callReceived` emission
private var currentCall: Call?

// `allowSkipVirtualAgent` is fetched separately from menu configuration
// it is not derived from the CallResponse.
let allowSkip = menuConfiguration.allowSkipVirtualAgent
let allowed = currentCall?.canEscalate(allowSkipVirtualAgent: allowSkip) ?? false
talkToAgentButton.isHidden = !allowed

הודעה קולית

מה ה-SDK מספק: startVoicemail(_ request: VoicemailRequest) ב-callService, בנוסף ל-enum‏ VoicemailReason שמתאר למה הפלטפורמה הציעה את האפשרות להשאיר הודעה קולית מלכתחילה (לדוגמה, חזרה למצב קודם אחרי שעות הפעילות, חזרה למצב קודם בגלל עומס יתר או הפניה זמנית).

מה שאתם יוצרים: נקודת הכניסה לתא הקולי בממשק המשתמש (בדרך כלל מוצגת כשהשדה VoiceCallChannel.voicemailReason מאוכלס, או כשמחזור החיים של השיחה מסתיים בהשארת הודעה בתא הקולי) וממשק המשתמש של ההקלטה עצמו.

דוגמה להטמעה

הצגת לחצן הדואר הקולי כשמוגדר voicemailReason, ואז התקשרות אל startVoicemail עם VoicemailRequest.

public enum VoicemailReason: String, Decodable {
    case afterHourDeflection
    case overCapacityDeflection
    case temporaryRedirection
}

func offerVoicemail(for menu: QueueMenu) async {
    guard let voice = menu.channels?.voiceCall,
          voice.voicemailReason != nil else {
        return
    }
    do {
        try await CCAI.shared.callService?.startVoicemail(
            VoicemailRequest(menuId: menu.id)
        )
    } catch {
        showVoicemailError(error)
    }
}

הפניית שיחות בזמן המתנה

כשהתור פתוח אבל זמן ההמתנה חורג מהסף שהאדמין הגדיר, הפלטפורמה יכולה להציע דרך חלופית – בדרך כלל שיחה חוזרת מתוזמנת או העברה לרשת הטלפוניה הציבורית (PSTN).

מה ה-SDK מספק: מטען ייעודי (payload) של CallDeflection שמתאר את האפשרות החלופית המוצעת, שאפשר לאחזר באמצעות getCallDeflection(callId:) ב-callService עבור השיחה הפעילה. בנוסף, הפלטפורמה משדרת את אותו מטען ייעודי (payload) דרך deflectionOffered המוציא לאור כשהפנייה למוציא לאור הופכת לזמינה באמצע ההמתנה. דגל CompanyResponse.preventDirectPstnCall נפרד מציין אם צריך להסתיר את החיוג ישירות לרשת הטלפוניה הציבורית (PSTN) בממשק המשתמש של הגיבוי.

מה יוצרים: את ההודעה להפניית השיחה (לדוגמה, זמן ההמתנה המשוער הוא 12 דקות. רוצה לקבוע שיחה חוזרת במקום זאת?) ואת לוגיקת ההסתעפות שמתחשבת בבחירה של המשתמש.

דוגמה להטמעה

תחפש את השיחה הפעילה עם getLastCallInProgress, תאחזר את ההפניה שהוצעה עם getCallDeflection(callId:), תשלב אותה עם CompanyResponse.preventDirectPstnCall ותציג את ההנחיה.

func evaluateWaitTimeDeflection() async {
    guard let currentCall = try? await CCAI.shared.callService?.getLastCallInProgress() else {
        return
    }
    let deflection = try? await CCAI.shared.callService?.getCallDeflection(
        callId: currentCall.id
    )
    guard let offer = deflection else { return }
    let company = try? await CCAI.shared.companyService?.get()
    let allowDirectPstn = company?.preventDirectPstnCall != true
    presentWaitTimeDeflection(offer, allowDirectPstn: allowDirectPstn)
}

הודעות קוליות (הודעות מערכת)

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

מה שיוצרים: כלום, במצב ברירת המחדל. אם אתם מעדיפים להציג את ההודעה בעצמכם (למשל, כטקסט של כתוביות בתוספת נגן אודיו משלכם), אתם יכולים לאתחל את מודול השיחה באמצעות playAudibleMessages = false ולהתקשר ישירות אל resolveMessages(menuId:).

דוגמה להטמעה

אפשר להשתמש בשיטת האתחול שמוגדרת כברירת מחדל לנתיב ההפעלה של ה-SDK, או להגדיר את playAudibleMessages = false ולפתור את ההודעות בעצמכם כדי להציג כתוביות ולהפעיל אודיו בממשק המשתמש שלכם.

// Option A default: SDK plays audible messages automatically.
CCAI.shared.initializeCall(CallOptions())

// Option B your app renders the announcements manually.
CCAI.shared.initializeCall(CallOptions(playAudibleMessages: false))
let messages = try await CCAI.shared.audibleMessageService?.resolveMessages(
    menuId: menu.id
)
for message in messages ?? [] {
    renderCaption(message.text)
    playAudio(message.audioURL)
}

אפשרויות מתקדמות CallOptions

‫CallOptions מציג קבוצה קטנה של מתגים לאפליקציות שצריכות לבטל את ההצטרפות לחוויית השיחות שמוגדרת כברירת מחדל.

  • ‫playAudibleMessages: Bool – אם הערך הוא false, ה-SDK לא מציג הודעות מערכת. צריך להציג אותן בעצמכם באמצעות audibleMessageService.

  • ‫callKitEnabled: Bool — כש-false, ה-SDK לא מציג את המסך המובנה של CallKit לשיחות נכנסות או יוצאות. משתמשים בזה כשהאפליקציה צריכה להציג ממשק משתמש משלה לשיחות נכנסות במקום להסתמך על ממשק המשתמש של מערכת iOS.

דוגמה להטמעה

מעבירים את המתגים אל CallOptions כשמאתחלים את מודול השיחות.

// Fully custom in-app call experience
CCAI.shared.initializeCall(
    CallOptions(
        playAudibleMessages: false,
        callKitEnabled: false
    )
)

שיתוף המסך

שיתוף המסך מאפשר לנציגי התמיכה לראות את המסך של המשתמש כדי לעזור לו לפתור בעיות. Google Cloud פרויקט תומך בשני מצבים של שיתוף מסך:

  • שיתוף בתוך האפליקציה: הנציג יכול לראות רק מה שקורה בתוך האפליקציה הספציפית שלכם.

  • שיתוף מלא של המכשיר (אופציונלי): הסוכן יכול לראות את כל המכשיר של המשתמש, כולל מסך הבית של iOS ואפליקציות אחרות. כדי לעשות את זה, צריך לבצע הגדרה מתקדמת של iOS באמצעות ReplayKit של אפל.

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

מה יוצרים: את הגדרת האתחול, את ההנחיות בממשק המשתמש לקבלת הסכמה מהמשתמשים, ואת תוסף השידור המובנה ל-iOS (אם תומכים במכשיר מלא).

שירות שיתוף המסך מספק שיטות לכל מחזור החיים של הסשן – create, activate, end, clear (iOS בלבד) – בנוסף לשיטות הגדרה updateOptions, enableRemoteControl ו-enableFullDeviceSharing. בקטעי המשנה הבאים מפורט תהליך השילוב העיקרי.

חתימות מלאות של רכיבי ה-method ופרטים על הפרמטרים של כל רכיבי ה-method לשיתוף מסך מופיעים במאמר בנושא Headless Mobile SDK – iOS API Reference.

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

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

import com.ccaiplatform.ccaikit.CCAI
import com.ccaiplatform.ccaikit.initializeScreenShare
import com.ccaiplatform.ccaikit.models.screenShare.ScreenShareOptions

// Minimal domain defaults to your instance's configured provider
CCAI.initializeScreenShare(
    context = this,
    options = ScreenShareOptions(
        key = "YOUR_COMPANY_KEY"
    )
)

// If your instance or provider requires an explicit domain:
// CCAI.initializeScreenShare(
//     context = this,
//     options = ScreenShareOptions(
//         key = "YOUR_COMPANY_KEY",
//         domain = "your_subdomain.ccaiplatform.com"
//     )
// )

בדיקת הזכאות לשיתוף מסך

לפני שמפעילים את האפשרות לשיתוף מסך, צריך לבדוק אם היא זמינה בצ'אט הנוכחי:

let isChatSupportingScreenShare = CCAI.shared.screenShareService != nil
    && chat?.isSupportingScreenShare == true

איך מטפלים בבקשות לשיתוף מסך

מטמיעים טיפול בבקשות לשיתוף מסך באמצעות screenShareService. יוצרים ScreenShareRequest ומטפלים בתגובה האסינכרונית:

func requestScreenShare(isFromRemote: Bool) async {
    guard let chatId = currentChatId else { return }
    guard let screenShareService = CCAI.shared.screenShareService else {
        handleError(ScreenShareError.serviceNotAvailable, message: "Request Screen Share")
        return
    }

    // Track whether this session is agent-initiated
    screenShareInitiatedFrom = isFromRemote ? .agent : .endUser

    if !isFromRemote {
        await sendScreenShareMessage(event: .screenShareRequestedFromEndUser)
    }

    do {
        let response = try await screenShareService.create(
            request: ScreenShareRequest(
                communicationId: chatId,
                communicationType: .chat,
                initiatedFrom: isFromRemote ? .agent : .endUser
            )
        )
        await sendScreenShareMessage(event: .screenShareCodeGenerated, response: response)
    } catch {
        await sendScreenShareMessage(event: .screenShareFailed)
        handleError(error, message: "Request screen share error")
    }
}

טיפול בשינויים במצב שיתוף המסך

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

CCAI.shared.screenShareService?.statePublisher
    .receive(on: DispatchQueue.main)
    .sink { state in
        currentScreenShareSessionState = state
        if state == .authorizing, screenShareInitiatedFrom == .agent {
            Task {
                do {
                    try await handleStartSession(isAccepted: true)
                } catch {
                    handleError(error, message: "Failed to start screen share")
                }
            }
        }
    }
    .store(in: &cancellables)

CCAI.shared.screenShareService?.requestPublisher
    .receive(on: DispatchQueue.main)
    .sink { request in
        switch request {
        case .session:
            if screenShareInitiatedFrom == .endUser {
                showScreenSharePrompt(.startSession)
            }
        case .remoteControl:
            showScreenSharePrompt(.remoteControl)
        @unknown default:
            break
        }
    }
    .store(in: &cancellables)

הספירה ScreenShareServiceState עוקבת אחרי התקדמות הסשן באמצעות הערכים .none, .pending, .authorizing, .active ו-.ended. בעל התוכן הדיגיטלי שולח בקשות להפעלת סשן ולשליטה מרחוק, והאפליקציה צריכה לתרגם אותן להנחיות לבקשת הסכמה שמוצגות ללקוחות.

שיתוף מסך של כל המכשיר (מתקדם)

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

הוספה של יעד לשידור

  • פותחים את פרויקט Xcode.

  • עוברים אל קובץ > חדש > יעד…

  • לוחצים על תוסף להעלאת שידור.

  • מזינים שם ליעד.

  • מבטלים את הסימון של Include UI Extension (הכללת תוסף ממשק המשתמש).

  • יוצרים את היעד ורושמים את מזהה החבילה שלו.

  • משנים את יעד ה-SDK של תוסף השידור ל-iOS 12.0 ואילך.

הגדרת שיתוף של מחזיק המפתחות

האפליקציה ותוסף האפליקציה צריכים לשתף סודות באמצעות ה-Keychain של iOS, באמצעות קבוצת Keychain משלהם.

  • ב-Xcode, עוברים לכרטיסייה Signing & Capabilities (חתימה ויכולות) בשני היעדים.

  • מוסיפים את היכולת Keychain Sharing.

  • מוסיפים io.cobrowse לקבוצות של מחזיקי מפתחות בשני היעדים.

עדכון הקובץ Info.plist של האפליקציה הראשית

מוסיפים את מזהה ה-bundle של התוסף לקובץ Info.plist של האפליקציה (ולא לקובץ Info.plist של התוסף):

<key>CBIOBroadcastExtension</key>
<string>your.app.extension.bundle.ID.here</string>

הוספה של CobrowseSDK ליעד של תוסף השידור

ב-Xcode, כשהיעד של תוסף השידור נבחר, לוחצים על הלחצן + בקטע Frameworks and Libraries (מסגרות וספריות) ומוסיפים את CobrowseSDK ליעד התוסף.

הטמעה של handler של תוסף

מערכת Xcode מוסיפה קובץ SampleHandler.swift ליעד שיצרתם קודם. מחליפים את תוכן הקובץ בתוכן הבא כדי שהקובץ יירש ממחלקת התוסף ReplayKit של ה-SDK:

import CobrowseSDK

class SampleHandler: CobrowseIOReplayKitExtension {
    // The Google Cloud project module automatically handles ReplayKit lifecycle methods
}

פיתוח והרצה

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

אם הגדרתם הכול בצורה נכונה, אחרי שתלחצו על הסמל הכחול העגול יוצג מסך שבו תוכלו לבחור את התוסף לשידור.

מגבלות של iOS SwiftUI בשיתוף מסך

  • עוטפים רכיבים אינטראקטיביים מרכזיים ב-UIKit – באזורים שצריך לאפשר לחיצה מרחוק, עוטפים אותם כפקדי UIKit (לדוגמה, UIButton) באמצעות UIViewRepresentable או UIViewControllerRepresentable. כך אפשר לוודא שלחיצות מרחוק יפעלו בצורה אמינה באמצעות נתיב ה-UIKit של Cobrowse.

  • העברת אירועי מגע מרחוק עם טיפול מותאם אישית במגע – באזורי SwiftUI שלא ניתן להחליף ב-UIKit, משתמשים בהחזרות מותאמות אישית של Cobrowse כדי להעביר אירועי מגע מרחוק ללוגיקת SwiftUI. ההטמעה כוללת שימוש ב-UIView או בכלי לזיהוי תנועות בהתאמה אישית כדי לטפל בקריאות חוזרות (callback), ולאחר מכן גישור בין אירועים ל-SwiftUI (באמצעות UIViewRepresentable בתוספת Coordinator, התראות או סגירות).

  • הצגת הנחיות אוטומטיות או חלופיות ברמת המוצר – לציין בבירור במסכי SwiftUI שהסוכנים יכולים רק לצפות; המשתמש צריך להקיש באופן מקומי, או להגביל אוטומטית את הרשאות השליטה מרחוק בדפים האלה תוך שמירה על גישה לצפייה בלבד.

דוגמה להטמעה של עטיפה ב-UIKit

struct RemoteControlButton: UIViewRepresentable {
    let title: String
    let action: () -> Void

    func makeUIView(context: Context) -> UIButton {
        let button = UIButton(type: .system)
        button.setTitle(title, for: .normal)
        button.addTarget(
            context.coordinator,
            action: #selector(Coordinator.buttonTapped),
            for: .touchUpInside
        )
        return button
    }

    func updateUIView(_ uiView: UIButton, context: Context) {
        uiView.setTitle(title, for: .normal)
    }

    func makeCoordinator() -> Coordinator {
        Coordinator(action: action)
    }

    class Coordinator: NSObject {
        let action: () -> Void

        init(action: @escaping () -> Void) {
            self.action = action
        }

        @objc func buttonTapped() {
            action()
        }
    }
}

// Usage in SwiftUI
struct ContentView: View {
    var body: some View {
        VStack {
            Text("This screen supports remote control")
            RemoteControlButton(title: "Clickable Button") {
                print("Button tapped remotely or locally")
            }
        }
    }
}

שיחות מתוזמנות

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

זיהוי יכולות

מה ה-SDK מספק: דגל scheduleEnabled ב-VoiceCallChannel שמציין אם התור שנבחר תומך בהזמנת שיחות עתידיות – בלי קשר לשאלה אם שיחות קוליות מיידיות (בזמן אמת) זמינות.

מה יוצרים: לוגיקה לבדיקת הדגל הזה לפני הצגת נקודת הכניסה לתזמון.

דוגמה להטמעה

בודקים את scheduleEnabled בערוץ של תור ההמתנה לשיחות קוליות. לא להשתמש ב-voiceCall != nil כשרת proxy – תור יכול לתמוך בשיחות קוליות מיידיות בלי לתמוך בשיחות מתוזמנות, ולהיפך.

func setupScheduledCallEntryPoint(for menu: QueueMenu) {
    guard let voiceChannel = menu.channels?.voiceCall else {
        // No voice channel at all hide both instant and scheduled call buttons
        hideCallNowButton()
        hideScheduleCallButton()
        return
    }

    // Instant voice call always show if voiceCall channel exists
    showCallNowButton()

    // Scheduled call check scheduleEnabled explicitly
    if voiceChannel.scheduleEnabled == true {
        showScheduleCallButton()
    } else {
        hideScheduleCallButton()
    }
}

הפניה למודל נתונים

// VoiceCallChannel.swift
public struct VoiceCallChannel: Decodable {
    // ...
    public let scheduleEnabled: Bool?  // true if scheduled calls are supported
    // ...
}

// ChannelType.swift
public enum ChannelType {
    case scheduleCall(deflectionType: DeflectionType?)
    // ...
}

אפשר גם לבדוק אם .scheduleCall מופיע ברשימת הערוצים המופעלים שמוחזרת על ידי QueueMenu.getEnabledChannels().

שליפת משבצות זמן פנויות

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

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

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

דוגמה להטמעה

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

let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
    menuId: menu.id,
    callIdForRescheduling: nil
) ?? []

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

let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
    menuId: menu.id,
    callIdForRescheduling: existingCallId
) ?? []

יצירת שיחה מתוזמנת

אחרי שהמשתמש בוחר משבצת זמן, יוצרים את השיחה המתוזמנת דרך callService.

מה ערכת ה-SDK מספקת: createScheduledCall API שקובע את המשבצת שנבחרה ומחזיר את רשומת השיחה המתוזמנת.

מה יוצרים: אימות של מספר טלפון בפורמט E.164, ממשק משתמש לאישור, אחסון מקומי של מזהה השיחה המתוזמנת ושחזור של שגיאות בתזמון.

דוגמה להטמעה

מעבירים את המשבצת שנבחרה, מספר הטלפון, מזהה התור ו-RecordingPermission.notAsked ב-ScheduledCallRequest.

let response = try await CCAI.shared.callService?.createScheduledCall(
    ScheduledCallRequest(
        menuId: menu.id,
        phoneNumber: userPhoneNumber,
        scheduleTime: selectedSlot,
        recordingPermission: .notAsked,
        callIdForRescheduling: nil,
        customData: nil,
        ticketId: nil
    )
)
saveScheduledCallId(response?.id)

מספר הטלפון צריך להיות בפורמט E.164, לדוגמה: +14155551234.

שינוי המועד של שיחה מתוזמנת

כדי לתזמן מחדש, מעבירים את המזהה הקיים של השיחה המתוזמנת כ-callIdForRescheduling.

מה מספק ה-SDK: אותם ממשקי API של חלונות זמן ויצירה, עם callIdForRescheduling שמשמש לזיהוי ההזמנה הקיימת.

מה יוצרים: ממשק המשתמש "change time", בדיקה מקומית של מזהה השיחה המתוזמנת המאוחסן ומצב האישור המעודכן אחרי יצירת ההזמנה החדשה.

דוגמה להטמעה

מעבירים את מזהה השיחה הקיים אל createScheduledCall אחרי שהמשתמש בוחר משבצת זמן חדשה.

let response = try await CCAI.shared.callService?.createScheduledCall(
    ScheduledCallRequest(
        menuId: menu.id,
        phoneNumber: userPhoneNumber,
        scheduleTime: newSelectedSlot,
        recordingPermission: .notAsked,
        callIdForRescheduling: existingCallId,
        customData: nil,
        ticketId: nil
    )
)
saveScheduledCallId(response?.id)

ביטול שיחה מתוזמנת

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

מה ערכת ה-SDK מספקת: API לביטול של מזהה שיחה מתוזמנת.

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

דוגמה להטמעה

מתקשרים אל cancelScheduledCall(callId:) עם המזהה ששמור, ואז מסירים את המזהה מהאחסון של האפליקציה.

try await CCAI.shared.callService?.cancelScheduledCall(callId: existingCallId)
clearScheduledCallId()

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

אימייל

מה ה-SDK מספק: כתובת האימייל של היעד שהוגדרה לתור הספציפי הזה, לצד הוראות שהאדמין רוצה שהמשתמש יראה (לדוגמה, צריך לכלול את מספר החשבון).

מה יוצרים: מסך כתיבת האימייל והנציג למעקב אחר השלמת הכתיבה. אתם יכולים ליצור טופס מותאם אישית משלכם או להשתמש בטופס המובנה של Apple MFMailComposeViewController.

דוגמה להטמעה

הקוד הזה שולף את כתובת האימייל לתמיכה ואת ההוראות מתוך ה-SDK. הוא פותח את הכלי המובנה לכתיבת אימיילים ב-iOS ומשתמש ב-MFMailComposeViewControllerDelegate כדי להאזין לרגע המדויק שבו המשתמש בוחר באפשרות שליחה או ביטול.

import UIKit
import MessageUI

class SupportViewController: UIViewController, MFMailComposeViewControllerDelegate {
    // 1. Trigger the email flow
    func openEmailComposer(for menu: QueueMenu) {
        guard let emailChannel = menu.channels?.email else { return }

        if MFMailComposeViewController.canSendMail() {
            let mail = MFMailComposeViewController()
            mail.mailComposeDelegate = self

            // Use the metadata provided by the SDK
            mail.setToRecipients([emailChannel.email].compactMap { $0 })
            mail.setMessageBody(emailChannel.instructionMessage ?? "", isHTML: false)
            present(mail, animated: true)
        } else {
            showError("Mail services are not configured on this device.")
        }
    }

    // 2. Track the outcome using Apple's delegate
    func mailComposeController(
        _ controller: MFMailComposeViewController,
        didFinishWith result: MFMailComposeResult,
        error: Error?
    ) {
        controller.dismiss(animated: true)

        switch result {
        case .sent:
            print("Email successfully sent!")
        case .cancelled:
            print("User cancelled the email.")
        case .saved:
            print("Email saved as draft.")
        case .failed:
            print("Email failed to send: \(error?.localizedDescription ?? "Unknown error")")
        @unknown default:
            break
        }
    }
}

מה ה-SDK מספק: רשימה של כתובות URL (כמו מרכז העזרה של החברה, מדיניות ההחזרים הכספיים או אפליקציית שותף) ושמות התצוגה שלהן, בדיוק כפי שהוגדרו בפורטל האדמינים.

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

דוגמה להטמעה

כלי עזר זה מקבל מחרוזת של כתובת URL ומציג אותה בדפדפן באפליקציה של Apple.

import SafariServices

func openHelpCenterLink(_ urlString: String) {
    guard let url = URL(string: urlString) else { return }
    let safariViewController = SFSafariViewController(url: url)
    present(safariViewController, animated: true)
}

ב-iOS, ‏ ExternalDeflectionLink לא מכיל url ברמה העליונה – הקישורים נמצאים בתוך מערך פנימי של links: [ExternalDeflection]?, וכל רשומה מופעלת תורמת לחצן אחד לתפריט הערוץ. מבצעים איטרציה במערך ומדלגים על כל הרשומות שבהן הדגל enabled הוא לא true.

func setupDeflectionLinks(for queueMenu: QueueMenu) {
    // Clear any previously-rendered buttons
    helpCenterStackView.arrangedSubviews.forEach { $0.removeFromSuperview() }

    guard let links = queueMenu.channels?.externalDeflectionLink?.links,
          !links.isEmpty else {
        helpCenterStackView.isHidden = true
        return
    }

    helpCenterStackView.isHidden = false

    for link in links where link.enabled == true {
        let button = UIButton(type: .system)
        button.setTitle(link.displayName, for: .normal)
        button.addAction(UIAction { [weak self] _ in
            self?.openHelpCenterLink(link.url)
        }, for: .touchUpInside)
        helpCenterStackView.addArrangedSubview(button)
    }
}

‫ExternalDeflectionLink חושף את enabled: Bool? ואת links: [ExternalDeflection]?. לכל ExternalDeflection יש url וdisplayName משלו. אם משתמשים ב-QueueMenu.getEnabledChannels(), ה-SDK פולט רשומה אחת של .externalDeflection(url:displayName:) לכל קישור מופעל. לכן, איטרציה ישירה של links ואיטרציה של הפלט של הערוצים המופעלים יוצרות את אותו סט של לחצנים.