SDK لنظام iOS — IngevoraMirage

SDK لنظام iOSالـ SDK لنظام iOS مكتبة Swift لتطبيقات iPhone. تجلب عدسات الوجه وتأثيرات الشاشة المنشورة في مساحة عملك باستخدام مفتاح API، وتتحقّق من كل ملف، وتحتفظ بكل إصدار على الهاتف، وترسمها داخل تطبيقك. وهي تتبع التنسيق وقواعد الرسم نفسها التي تتبعها المعاينة الحية في الاستوديو، فترسم ما يراه مصمّموك في المحرّر.الإصدار الحالي هو 0.2.0. وهو منشور بصيغة ثنائية، مع تطبيق نموذجي، على github.com/Ingevora/mirage-ios.ما تحتاج إليه

نظام iOS 16 أو أحدث، على iPhone.

Xcode 26.2 أو أحدث.

مفتاح API للتطبيق، من Workspace → API keys (مساحة العمل ← مفاتيح API). راجع مفاتيح API.

معرّفات عدسات الوجه وتأثيرات الشاشة المنشورة التي يعرضها تطبيقك. تسردها صفحة Developers (المطوّرون) في المحرّر.

التثبيتفي Xcode، اختر File → Add Package Dependencies…، وأدخل https://github.com/Ingevora/mirage-ios، واختر الإصدار 0.2.0 تحديدًا. أو أضفها إلى Package.swift:

swift

.package(url: "https://github.com/Ingevora/mirage-ios.git", exact: "0.2.0"),

ثم أضف المنتج إلى الهدف (target) الخاص بك:

swift

.product(name: "IngevoraMirage", package: "mirage-ios"),

إنشاء العميلأنشئ عميلًا واحدًا للتطبيق، بمفتاح API الخاص بالتطبيق، واحتفظ به.

swift

import IngevoraMirage

let mirage = MirageClient(configuration: .init(apiKey: "mk_…"))

// Prefetch what the app will show, so it starts without waiting.
let effect = try await mirage.prefetchEffect(id: "7c1e9a2b-4d3f-4a6e-8b5c-2f9d0e1a3b4c")

الخيوط. كل استدعاء من نوع async، ويمكن إجراؤه من أي خيط.

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

الأحدث أو المثبّت. تقبل prefetchLens(id:version:) وprefetchEffect(id:version:) المعامل version لتثبيت إصدار بعينه؛ ومن دونه تتبعان الإصدار الأحدث. راجع الإصدارات: الأحدث والمثبّت.

تأثيرات الشاشة

swift

// One player per screen that shows effects; keep it, for example in the screen's view model.
let player = MirageEffectPlayer(mirage: mirage)

// SwiftUI: an overlay above the screen's content. It passes every touch through.
content.overlay { MirageEffectOverlay(player: player).ignoresSafeArea() }
// UIKit: add MirageEffectView(player: player) above the content, pinned to the screen's edges.

player.play(effectId: "7c1e9a2b-4d3f-4a6e-8b5c-2f9d0e1a3b4c")
player.onEnd = { playback in
    if playback.state == .ended(.finished) {
        // the effect finished
    }
}

استخدم المشغّل على الـ main actor. أما الرسم فيجري على خيط خاص به.

التشغيل لا ينتظر أبدًا: التأثير الذي لم يُنزَّل بعد يُتخطّى ويبدأ تنزيله، فتنجح محاولة التشغيل اللاحقة.

يُشغَّل 4 تأثيرات على الأكثر في الوقت نفسه. ويُحترم إعداد Reduce Motion (تقليل الحركة): يتوقف الاهتزاز والنبض والوميض.

لتشغيل تأثير واحد على عدة هواتف، يُنشئ المُرسِل إشارة (cue) باستخدام player.cue(effectId:)، الذي ينزّل التأثير أولًا. ينقل تطبيقك الإشارة (فهي من نوع Codable)، ويشغّلها كل هاتف باستخدام player.play(cue).

عدسات الوجه

swift

// One player per camera session; keep it.
let lens = MirageLensPlayer(mirage: mirage)
lens.attach(lensId: "3f2b8c1e-6d4a-4f7e-9b2c-8a1d5e6f7a90") // stored at once, else downloaded

// On your video queue, for every camera frame: send it, and show the frame that comes back.
let drawn = lens.process(pixelBuffer, time: presentationTime, orientation: .right)

// The self-view, in SwiftUI; MirageLensPreviewView(player: lens) in UIKit.
MirageLensPreview(player: lens)

اربط العدسة على الـ main actor. واستدعِ process على طابور الفيديو الخاص بك، إطارًا واحدًا في كل مرة.

تكون الإطارات بصيغة 420f أو 420v أو BGRA، مع الاتجاه الذي يجعلها معتدلة (.right للكاميرا الأمامية في تطبيق بوضع عمودي). والإطار المرسوم له الحجم والصيغة والاتجاه أنفسها.

تعثر الـ SDK على الوجه باستخدام إطار Vision من Apple. إذا كان تطبيقك يتتبّع الوجوه بالفعل، فمرّر نتائجك عبر process(_:time:orientation:face:)، حتى لا يعمل Vision مرتين.

لا تكلّف العدسة تطبيقك أي إطار. فعند عدم وجود عدسة، أو عند أي إخفاق، أو حين يكون الهاتف أبطأ من أن يشغّلها، يمرّ الإطار دون أي تعديل، وتوضّح قيمة state في المشغّل السبب.

أحداث تطبيقكيرسل تطبيقك أسماء أحداثه الخاصة، فتعمل المُشغِّلات التي تستمع إليها:

swift

player.fire(event: "order.placed") // every running screen effect
lens.fire(event: "round.start")    // the attached face lens

يُتجاهل أي اسم لا يسمح به التنسيق. راجع المُشغِّلات وأحداثك.الأخطاءكل إخفاق يكون من نوع MirageError:

الخطأ

المعنى

من الـ API

invalidAPIKey

المفتاح مفقود أو غير معروف أو ملغى.

401

productDisabled

عدسات الوجه أو تأثيرات الشاشة غير مفعّلة لمساحة عملك.

403

notFound

لا يوجد عنصر كهذا لهذا المفتاح، أو المعرّف ليس UUID.

404

unavailable

تعذّر الوصول إلى الـ API أو إلى الملفات (انقطاع الاتصال، أو انتهاء المهلة، أو بلوغ الحد الشهري، أو خطأ في الخادم)، ولا يوجد إصدار مخزّن.

429، 5xx

engineTooOld

يحتاج العنصر إلى SDK أحدث، ولا يوجد إصدار مخزّن تستطيع هذه الـ SDK رسمه.

—

unsupportedFormat

ملف البيان (manifest) من إصدار تنسيق لا تقرؤه هذه الـ SDK.

—

invalidPackage

أخفق ملف في أحد الفحوصات: حجمه، أو بصمة SHA-256 الخاصة به، أو قواعد ملف البيان، أو صورة.

—

قد يضيف إصدار لاحق حالات جديدة إلى أنواع enum في الـ SDK، لذا تحتاج عبارة switch على أحدها إلى @unknown default:

swift

switch error {
case .invalidAPIKey: showKeyHelp()
case .notFound: showMissing()
default: showRetry() // or list every case, then `@unknown default:`
}

راجع الأخطاء والحدود.التخزين المؤقت وطلبات التسليم

التحقّق ثم الاحتفاظ. تتحقّق الـ SDK من بصمة SHA-256 لملف البيان ولكل صورة، كما يصف التنزيل الآمن، وتحتفظ على الهاتف بكل إصدار تحقّقت منه، فلا يُنزَّل الإصدار إلا مرة واحدة. يوجد التخزين المؤقت في Library/Caches/com.ingevora.mirage وتبلغ سعته 100 MiB افتراضيًا؛ وتُحذف الإصدارات الأقل استخدامًا مؤخرًا أولًا. وتُفرغه الدالة clearCache().

سؤال واحد كل ساعة. يُعتمد الإصدار الأحدث من العنصر لمدة ساعة (freshness، و3600 ثانية افتراضيًا) قبل سؤال الـ API مجددًا. وكل سؤال هو طلب تسليم يُحتسب من الحد الشهري لمساحة عملك.

الرجوع إلى المخزّن. حين يتعذّر استخدام أحدث إصدار (انقطاع الاتصال، أو الحالة 429، أو تنزيل تالف)، يُستخدم بدلًا منه أحدث إصدار موجود على الهاتف، وتوضّح قيمة source في نتيجة الجلب المسبق السبب (.cacheFallback).

المسوداتلا تشغّل الـ SDK إلا عدسات الوجه وتأثيرات الشاشة المنشورة. لتجربة مسودة عدسة وجه قبل نشرها، استخدم الاختبار على هاتفك: يفتح رمز QR الخاص بها المسودة على كاميرا هاتفك، داخل المتصفح.الخصوصيةيتضمّن إطار العمل ملف بيان خصوصية (PrivacyInfo.xcprivacy): لا تجمع الـ SDK أي بيانات، ولا تُجري أي تتبّع، ولا تستخدم أيًا من واجهات API التي تطلب Apple تبريرًا لاستخدامها. ولا تغادر إطارات الكاميرا الهاتف أبدًا.التطبيق النموذجييعرض الملف Example/MirageExample.xcodeproj في المستودع عملية الدمج كاملة في أربعة ملفات قصيرة. افتحه، واختر فريقك ومعرّف حزمة (bundle ID) خاصًا بك (من Signing & Capabilities في الهدف)، وشغّله على iPhone. الصق مفتاح API الخاص بك، ثم معرّف عدسة وجه أو تأثير شاشة منشور.صفحات ذات صلة

البدء السريع — الخطوات نفسها، في صفحة واحدة.

واجهة التسليم — ما تستدعيه الـ SDK نيابة عنك.

SDK لنظام Android — ما هو مخطّط لتطبيقات Android.