ScanRamz — دليل استخدام الماسح

البداية السريعة

حط عنصرًا فاضيًا في المكان اللي عاوز الماسح يظهر فيه، وحمّل الحزمة، ونادي ScanRamz.create:

<div id="scanner" style="width:100%;max-width:480px"></div>

<script src="https://aiscan.afaq-digital.com/sdk/scanramz.js"></script>
<script>
  const scanner = ScanRamz.create({
    license: "SR-XXXX-XXXX-XXXX",          // مفتاح الترخيص بتاعك
    container: "#scanner",
    onScan: (result) => {
      console.log(result.format, result.text);   // مثال: "code128" "2300228790"
    },
    onError: (error) => console.warn(error.code, error.message),
  });

  scanner.start();   // بيطلب إذن الكاميرا وبيبدأ المسح
</script>

الحزمة ملف واحد فيه كل حاجة — مفيش ملفات تانية ولا CSS ولا مكتبات. والماسح بياخد عرض العنصر الحاوي؛ لو العنصر ليه ارتفاع محدد بيملاه، وإلا بياخد شكل الكاميرا.

الخيارات — ScanRamz.create(options)

الدوال

كلها على الكائن اللي ScanRamz.create بيرجّعه. ولا واحدة منها بترمي استثناء — أي خطأ بييجي في onError.

scanner.start() — تشغيل

بتشغّل الكاميرا وبتبدأ المسح. بترجّع Promise قيمته true لو اشتغلت وfalse لو فشلت (والسبب في onError). لازم تتنادى من ضغطة زر على iPhone لو الصفحة لسه ما أخدتش إذن الكاميرا.

const ok = await scanner.start();
if (!ok) alert("الكاميرا ما اشتغلتش");

scanner.stop() — إيقاف

بتوقف المسح وبتقفل الكاميرا (لمبة الكاميرا بتطفي). تقدر تنادي start() تاني بعدها.

scanner.pause() و scanner.resume() — إيقاف مؤقت

pause() بتوقف القراءة والكاميرا لسه شغّالة والصورة ظاهرة — مفيدة وإنت بتعرض نتيجة أو نافذة تأكيد. وإنت في الوضع ده مفيش مسحات بتتحسب. resume() بترجّع المسح فورًا (من غير طلب إذن تاني).

onScan: (result) => {
  scanner.pause();                      // وقّف لحد ما المستخدم يأكّد
  showConfirm(result.text, () => scanner.resume());
}

scanner.setAI(true | false) — تشغيل/إيقاف الذكاء الاصطناعي

بتشغّل أو توقف موديل الذكاء الاصطناعي في أي وقت، والتغيير فوري. scanner.aiEnabled بترجّع الحالة الحالية.

scanner.setAI(false);          // الكاشف العادي بس
scanner.setAI(true);           // رجّع الذكاء الاصطناعي
console.log(scanner.aiEnabled);

scanner.setFormats([...]) — تحديد الأنواع

بتحدد الأنواع اللي الماسح يدوّر عليها. ابعت null للرجوع لكل الأنواع. scanner.getFormats() بترجّع الأنواع المفعّلة. شوف قايمة الأنواع.

scanner.setFormats(["code128"]);         // ملصقات الأصول بس
scanner.setFormats(["qr", "datamatrix"]);
scanner.setFormats(null);                // الكل

scanner.setSelect("auto" | "tap" | "tapIfMultiple") — اختيار الرمز بالضغط

ملصق جهاز عليه كذا باركود (السيريال، الموديل، MAC…) وإنت عاوز واحدًا بس؟ في وضع "tap" الماسح ما بيبعتش حاجة لوحده: كل الرموز اللي في الصورة بتظهر بإطار أزرق وفوق كل واحد قيمته، والمستخدم يضغط على الرمز (أو على قيمته) فيوصل onScan بالرمز ده بس — وهو بس اللي بيتحسب مسحًا.

const scanner = ScanRamz.create({
  license: "SR-XXXX-XXXX-XXXX",
  container: "#scanner",
  select: "tap",                        // المستخدم يختار الرمز بالضغط
  onScan: (r) => { document.getElementById("serial").value = r.text; scanner.stop(); },
});

scanner.setSelect("auto");              // تغييره في أي وقت
console.log(scanner.getSelect());

scanner.setTorch(true | false) — الكشاف

بتشغّل أو تطفي كشاف الموبايل. بترجّع Promise بالحالة الفعلية — false لو الكاميرا ما بتدعمش (كاميرات اللابتوب، وبعض متصفحات الموبايل).

scanner.setZoom(x) و scanner.getCapabilities() — الزوم

setZoom بتظبط الزوم يدويًّا وبترجّع القيمة اللي اتطبقت فعلًا. getCapabilities() بترجّع إمكانيات الكاميرا الشغّالة:

const caps = scanner.getCapabilities();
// { torch: true, zoom: { min: 1, max: 4, step: 0.1, current: 1, hardware: true } }
scanner.setZoom(2);

scanner.scanImage(file) — قراءة صورة

بتقرا صورة بدل الكاميرا: ملف مرفوع، Blob، عنصر <img>، أو <canvas>. بترجّع Promise فيه مصفوفة بكل الرموز اللي في الصورة (فاضية لو مفيش). بتشتغل والكاميرا شغّالة أو واقفة، وما بتناديش onScan.

<input type="file" id="photo" accept="image/*">
<script>
  document.getElementById("photo").onchange = async (e) => {
    const results = await scanner.scanImage(e.target.files[0]);
    for (const r of results) console.log(r.format, r.text);
  };
</script>

scanner.getUsage() — الاستهلاك

بترجّع استهلاك الاشتراك: المسحات المستهلكة، الحصة، المتبقي، وتاريخ الانتهاء. المسح بيتحسب مرة لكل رمز (شوف repeatDelayMs)، وكل رمز بترجّعه scanImage بيتحسب مسحًا.

scanner.getUsage();
// { scans: 12, limit: 5000, remaining: 4988, expiresAt: "2027-01-01", licensed: true }

scanner.destroy() — إزالة

بتقفل الكاميرا وبتشيل الماسح من الصفحة وبتحرر الذاكرة. الكائن ما ينفعش يتستخدم بعدها — اعمل واحدًا جديدًا بـ ScanRamz.create. ناديها لما المستخدم يسيب الصفحة في تطبيقات الصفحة الواحدة (React، Vue…).

scanner.state — الحالة

نص: "idle" (واقف)، "starting" (مستني إذن الكاميرا)، "scanning" (بيمسح)، "paused" (متوقف مؤقتًا)، "destroyed".

الذكاء الاصطناعي: بيعمل إيه، وإمتى توقفه

الماسح فيه جزئين: قارئ بيفك الرمز (كود دقيق مضمون)، وموديل ذكاء اصطناعي صغير بيبص على الصورة كلها ويقول "الرمز هنا". الموديل ما بيقراش — بيوجّه القارئ والزوم والفوكس للمكان الصح، فالرمز البعيد أو اللي وسط كلام وزحمة بيتلقط أسرع.

النتيجة المقروءة واحدة في الحالتين. وقّفه لو أجهزتك ضعيفة جدًّا أو الرموز دايمًا قريبة وواضحة. كل شغل الموديل على جهاز المستخدم نفسه — الصورة ما بتطلعش من الجهاز عشان تتحلل.

شكل النتيجة

اللي بيوصل onScan، وكل عنصر في مصفوفة scanImage:

{
  format: "code128",              // نوع الرمز
  text: "2300228790",             // النص المقروء
  corners: [{ x: 412, y: 300 }, …],   // أركان الرمز في صورة الكاميرا (بالبكسل)
  timeMs: 3.4,                    // زمن القراءة
  ai: false,                      // true لو الموديل هو اللي دلّ على مكان الرمز
  details: { … }                  // تفاصيل فنية (الإصدار، تصحيح الأخطاء…)
}

الأنواع المدعومة

القيم اللي بتتبعت في formats وsetFormats (والقايمة كلها في ScanRamz.FORMATS):

الرموز معكوسة الألوان (أبيض على أسود، زي ملصقات الأجهزة) مدعومة تلقائيًّا لكل الأنواع.

الأخطاء — onError({ code, message })

أمثلة كاملة

ماسح بأزرار تشغيل وإيقاف ومفتاح للذكاء الاصطناعي

<div id="scanner" style="width:100%;max-width:480px"></div>
<button id="start">تشغيل</button>
<button id="stop">إيقاف</button>
<label><input type="checkbox" id="ai" checked> الذكاء الاصطناعي</label>
<p id="out"></p>

<script src="https://aiscan.afaq-digital.com/sdk/scanramz.js"></script>
<script>
  const scanner = ScanRamz.create({
    license: "SR-XXXX-XXXX-XXXX",
    container: "#scanner",
    formats: ["code128", "qr"],
    beep: true,
    onScan: (r) => { document.getElementById("out").textContent = r.text; },
    onError: (e) => { document.getElementById("out").textContent = e.message; },
  });
  document.getElementById("start").onclick = () => scanner.start();
  document.getElementById("stop").onclick = () => scanner.stop();
  document.getElementById("ai").onchange = (e) => scanner.setAI(e.target.checked);
</script>

جرد: كل رمز يتبعت لسيرفرك مرة واحدة

const scanner = ScanRamz.create({
  license: "SR-XXXX-XXXX-XXXX",
  container: "#scanner",
  formats: ["code128"],
  onScan: async (r) => {
    await fetch("/api/inventory", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ code: r.text }),
    });
  },
});
scanner.start();

مسح رمز واحد ثم الإغلاق

const scanner = ScanRamz.create({
  license: "SR-XXXX-XXXX-XXXX",
  container: "#scanner",
  onScan: (r) => {
    scanner.stop();                               // اقفل الكاميرا
    document.getElementById("code").value = r.text;   // حط القيمة في خانة الإدخال
  },
});

React / Vue / تطبيق صفحة واحدة

// عند ظهور المكوّن
const scanner = ScanRamz.create({ license: "…", container: element, onScan });
scanner.start();

// عند إزالة المكوّن — مهم: بيقفل الكاميرا
scanner.destroy();

الخصوصية: إيه اللي بيطلع من جهاز المستخدم؟

القراءة كلها بتحصل على جهاز المستخدم: الفيديو والنص المقروء ما بيتبعتوش لأي سيرفر. اللي بيتبعت لسيرفر الترخيص: مفتاح الترخيص، وعدّاد المسحات (كام مسحًا ومن أي نوع) — من غير قيم الرموز.

عيّنات تحسين الماسح (اختيارية ومقفولة افتراضيًّا): لو وافقت في اشتراكك على المساعدة في تحسين الماسح، بيتبعت كل فترة (تقريبًا مرة كل 10 مسحات) صورة واحدة مصغّرة جدًّا ورمادية (حوالي 384 بكسل — الكلام فيها ما بيتقراش) ومعاها مكان الرمز ونوعه. قيمة الرمز المقروءة ما بتتبعتش أبدًا. الصور دي بتتستخدم بس في تدريب الماسح على إنه يلاقي الرموز أسرع.

مشاكل شائعة

المتصفحات: الإصدارات الحديثة من Chrome و Edge و Firefox و Safari، على الموبايل والكمبيوتر. الكشاف والزوم الحقيقي (زوم العدسة) متاحين في Chrome على أندرويد؛ في باقي المتصفحات الزوم رقمي.