iOS SDK

المتطلبات#

• iOS 15.0+ (تدرّجات ورقة أدق على iOS 16+، مع احتياطي نظامي فيما دونه).
• Swift 5.9+.
• بدون أي تبعيات خارجية — فقط Foundation وSwift Concurrency وSwiftUI وUIKit.

تعتمد على منتج RespondoSDK، الذي يعيد تصدير RespondoCore متعدد المنصات.

التثبيت#

أضف الحزمة عبر Swift Package Manager. في Xcode: File → Add Package Dependencies… وأدخل https://github.com/respondo-app/sdk-ios، أو صرّح عنها في Package.swift الخاص بك، ثم اعتمد على منتج RespondoSDK.

dependencies: [
    .package(url: "https://github.com/respondo-app/sdk-ios", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RespondoSDK", package: "sdk-ios")
        ]
    )
]

ثم استوردها في الكود:

import RespondoSDK

التهيئة#

هيّئ مرة واحدة عند الإطلاق، ثم استدعِ Respondo.open() في أي مكان. طريقة دورة الحياة هي initialize (فالكلمة init محجوزة في اللغة).

import SwiftUI
import RespondoSDK

@main
struct MyApp: App {
    init() {
        Respondo.initialize(
            RespondoConfig(
                agentId: "<agent-uuid>",
                channelId: "<channel-uuid>"
                // baseUrl nil -> https://api.respondo.ai
            )
        )
    }

    var body: some Scene {
        WindowGroup {
            Button("Support") { Respondo.open() }
        }
    }
}

واجهة Respondo آمنة من حيث الخيوط. تُوضع النداءات المُجراة بُعيد initialize في طابور وتُطبَّق بمجرد اكتمال التهيئة غير المتزامنة.

تعريف المستخدمين#

افتراضياً يكون كل زائر مجهولاً. عند الإطلاق الأول تولّد حزمة SDK visitor_id ثابتاً وتحتفظ به في سلسلة المفاتيح (keychain)، فيجد المستخدم العائد محادثته من جديد. لا يوجد مفتاح API لتضمينه — إذ تُحمى كل محادثة برمز جلسة خاص بها يصكّه الخلفية ويدفعه إلى الأمام مع كل رسالة، فلا يضطر الزائر المجهول قط إلى إعادة المصادقة.

استدعِ identify بمجرد تسجيل دخول مستخدمك. يربط ذلك هويته الحقيقية بحيث يتبعه سجلّه عبر الأجهزة وعمليات إعادة التثبيت، ويظهر اسمه وبريده الإلكتروني بجوار المحادثة في صندوق الوارد لديك بدلاً من زائر مجهول.

الـ userHash هو توقيع تحسبه خلفيتك من identity_secret الخاص بالوكيل — HMAC-SHA256(secret, userId) (أو البريد الإلكتروني حين لا يوجد userId)، مُرمَّزاً كنظام ست عشري بأحرف صغيرة. يثبت السر أن الهوية أصيلة، لذا يجب أن يبقى على خلفيتك فقط ولا يُشحن أبداً في التطبيق. راجع صفحة التحقق من الهوية للاطلاع على الصيغة الكاملة وأمثلة جانب الخادم.

// يأتي userHash من خلفيتك (HMAC-SHA256 على userId) —
// لا تحسبه أبداً داخل التطبيق.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// عند تسجيل الخروج: أبطل الجلسة وابدأ زائراً مجهولاً جديداً.
Respondo.reset()

إذا كان التجزئة مفقودة أو خاطئة، فلا يُلقى أي استثناء: تُبقي الخلفية الزائر مجهولاً بصمت، وتستمر المحادثة في العمل، وتفقد ببساطة الربط عبر الأجهزة حتى يُقدَّم تجزئة صالحة. لا يعمل التحقق إلا عندما يكون للوكيل identity_secret مضبوط — اتركه فارغاً أثناء التطوير ويُقبل userId / البريد الإلكتروني كما هما.

Observables و delegate#

اقرأ الحالة على هيئة دوال جلب متزامنة، أو AsyncStream تفاعلية، أو عبر RespondoDelegate. تصل التدفقات واستدعاءات المفوَّض على المُمثِّل الرئيسي (main actor).

// تدفق تفاعلي لأعداد غير المقروء.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// مفوَّض للشارات واحتياطيات الروابط العميقة.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

تتبّع الشاشة#

أبلغ عن الشاشة الحالية عند كل تنقّل حتى تتمكن العروض التشويقية الاستباقية والاستهداف على مستوى الصفحة من المطابقة معها (static func setCurrentScreen(_ name: String?)). مرّر nil لمسحها؛ ومع كل تغيير يُعاد تقييم العرض التشويقي الاستباقي للشاشة الجديدة.

Respondo.setCurrentScreen("pricing")

الخطوات التالية#

اربط الإشعارات الفورية والتحقق من الهوية. أما غلاف UIKit RespondoChatViewController، وسطح المفوَّض الكامل، واستكشاف الأخطاء وإصلاحها فمشمولة في دليل بدء استخدام iOS SDK؛ ومصادر الحزمة متاحة للعموم على GitHub.