المفاهيم

تُعرّف هذه الصفحة الأفكار القليلة التي يقوم عليها كلّ شيء في فيديوهاتي. كلٌّ منها مشروح بكلمات بسيطة أوّلًا، تليها ملاحظة قصيرة عن موضعه في الواجهة البرمجية. يمكنك قراءتها من أوّلها إلى آخرها، أو الانتقال إلى المصطلح الذي تحتاجه.

الحساب

الحساب هُويّة مؤسّستك على فيديوهاتي. هو ما تسجّل الدخول إليه، ويملك فواتيرك ومشاريعك. يستطيع الحساب الواحد أن يضمّ مشاريع كثيرة — مثلًا، مشروعًا لكلّ موقع أو تطبيق تُديره.

في لوحة التحكّم: تسجّل الدخول إلى حسابك على app.videohati.com، وهو ما يملك مشاريعك وفواتيرك.

المشروع

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

في لوحة التحكّم: تُنشئ المشاريع وتُديرها على app.videohati.com. ينتمي كلّ فيديو ومفتاح إلى مشروع واحد بالضبط.

مفتاح الواجهة البرمجية

مفتاح الواجهة البرمجية هو السرّ الذي تستخدمه شيفرتك لتُثبت أحقّيّتها في التصرّف ضمن مشروع. ولأنّه سرّ، فمكانه خادمك فقط، لا متصفّح ولا تطبيق جوّال.

تأتي المفاتيح بوضعين ويمكن أن تحمل صلاحيّات مختلفة:

• المفاتيح التجريبية تبدأ بـ vh_test_ وتتصرّف في بيانات تجريبية مفصولة عن محتواك الحقيقيّ. المفاتيح المباشرة تبدأ بـ vh_live_ وتتصرّف في محتواك الحقيقيّ. البادئة وحدها تحدّد الوضع.
• يحمل المفتاح صلاحيّة قراءة (read)، أو كتابة (write)، أو كلتيهما. امنح كلّ مفتاح ما يحتاجه من صلاحيّة فقط.
• تُعرَض القيمة الكاملة للمفتاح مرّة واحدة فقط، عند إنشائه. انسخها حينها واحفظها بأمان.
• إن تسرّب مفتاح يومًا، فبدّله (rotate): يُصدر التبديل سرًّا جديدًا ويُحيل القديم، فتتوقّف القيمة المسرَّبة عن العمل.

في لوحة التحكّم: تُنشئ المفاتيح وتُبدّلها وتُلغيها على app.videohati.com.

الفيديو وحالاته

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

الحالات التي يمكن للواجهة البرمجية الإبلاغ عنها هي:

المسار الذي تتبعه معظم المقاطع هو uploading ← uploaded ← encoding ← ready. أمّا الفيديو الذي تتعذّر معالجته فينتهي عند failed بدلًا من ذلك، مع بيان السبب.

في الواجهة البرمجية: تقرأ حالة الفيديو state بـ videos.get، أو تنتظر وصوله إلى ready بـ videos.waitForState. راجع حِزمة تطوير Node.

جلسة التشغيل

جلسة التشغيل إذنٌ قصير الأمد يتيح لمشاهد واحد أن يشاهد فيديو واحدًا. يُنشئ خادمك جلسةً حين يكون المشاهد على وشك المشاهدة، ويسلّمه رمز جلسة ورابطًا مؤقّتًا — لا مفتاح الواجهة البرمجية أبدًا.

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

في الواجهة البرمجية: تُنشئ الجلسة بـ playback.createSession في خادمك؛ ويُبقيها المشغّل حيّة أثناء مشاهدة المشاهد.

خطّاف الويب

خطّاف الويب (webhook) رسالة ترسلها فيديوهاتي إلى خادمك حين يقع حدثٌ ما — مثلًا، حين تنتهي معالجة فيديو. فبدل أن يسأل تطبيقك مرارًا "هل جهز بعد؟"، تُخبرك فيديوهاتي في اللحظة التي يجهز فيها. تسجّل عنوانًا، فترسل فيديوهاتي إليه رسالة موقَّعة عن كلّ حدث.

أنواع الأحداث الثمانية هي:

كلّ رسالة موقَّعة، فيستطيع خادمك التأكّد من أنّها جاءت فعلًا من فيديوهاتي قبل أن يتصرّف بناءً عليها.

في الواجهة البرمجية: تسجّل العناوين بـ webhooks.register، وتتحقّق من كلّ رسالة بـ webhooks.verify (أو verifyWebhookSignature). راجع حِزمة تطوير Node وحِزمة تطوير Laravel.

العلامة المائية ونصّ المشاهد

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

في الواجهة البرمجية: تضبط نصّ العرض حين تُنشئ جلسة، عبر خيار viewerDisplayText في playback.createSession.