دليل: التضمين في أي موقع (HTML عادي، ووردبريس، أي نظام إدارة محتوى)

لا تحتاج إلى إطار عمل لعرض فيديو فيديوهاتي. هناك طريقتان للتضمين، وتعتمد الطريقة المناسبة على مستوى ظهور الفيديو:

• الفيديوهات العامة وغير المدرجة — الصق <iframe> (أو شارك رابطًا فقط). دون أي كود خادم إطلاقًا. ابدأ من القسم التالي.
• الفيديوهات الخاصة — يصدر خادمك رمز جلسة قصير العمر لكل مشاهد، ويركَّب المشغّل من وسم سكربت. ويبقى مفتاح الواجهة البرمجية على الخادم طوال الوقت. ابدأ من أنشئ جلسة تشغيل.

تضمين دون كود: الفيديوهات العامة وغير المدرجة

يبدأ كل فيديو بمستوى private (خاص). بدّله إلى unlisted (غير مدرج — يشاهده من يملك الرابط، ولا تفهرسه محركات البحث) أو public (عام) من بطاقة المشاركة والتضمين في صفحة الفيديو داخل اللوحة، أو عبر الواجهة البرمجية:

curl -X PATCH https://api.videohati.com/v1/videos/01JZ9WV3N8GQ5T2M7K4C6XBARH \
  -H "Authorization: Bearer $VIDEOHATI_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "visibility": "unlisted" }'

بعد أن يصبح الفيديو غير مدرج أو عامًا، تتاح ثلاثة خيارات دون أي كود:

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

https://cdn.videohati.com/watch/01JZ9WV3N8GQ5T2M7K4C6XBARH

إطار iframe. الصق هذا حيث يجب أن يظهر الفيديو (الحاوية تحافظ على نسبة 16:9 عند أي عرض):

<div style="position:relative;padding-top:56.25%;">
  <iframe
    src="https://cdn.videohati.com/embed/01JZ9WV3N8GQ5T2M7K4C6XBARH"
    style="position:absolute;inset:0;width:100%;height:100%;border:0;"
    allow="autoplay; fullscreen; encrypted-media; picture-in-picture"
    allowfullscreen loading="lazy" title="Videohati"></iframe>
</div>

أضِف ?lang=en إلى رابط /watch أو /embed لواجهة مشغّل إنجليزية؛ العربية هي الافتراضية. وأضِف autoplay=1 إلى رابط /embed لبدء التشغيل مكتوم الصوت عند التحميل.

oEmbed. المنصات التي تدعم اكتشاف oEmbed (ووردبريس وNotion ومعظم أنظمة إدارة التعلّم) تحوّل رابط المشاهدة إلى مشغّل فور لصقه — دون أي HTML. نقطة النهاية هي https://cdn.videohati.com/oembed?url=<watch-url>.

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

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

1. أنشئ جلسة تشغيل على الخادم

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

curl -X POST https://api.videohati.com/v1/playback/sessions \
  -H "Authorization: Bearer $VIDEOHATI_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "videoId": "01JZ9WV3N8GQ5T2M7K4C6XBARH", "viewerDisplayText": "Ahmed K." }'

{
  "sessionId": "01JZ9WV3N8GQ5T2M7K4C6XBARK",
  "sessionToken": "01JZ9WV3N8GQ5T2M7K4C6XBARK.1781485200.bXktbWFj",
  "manifestUrl": "https://cdn.videohati.com/…/master.m3u8",
  "expiresAt": "2026-07-05T12:00:00Z"
}

import { Videohati } from "@videohati/node";

const client = new Videohati({ apiKey: process.env.VIDEOHATI_API_KEY });

const session = await client.playback.createSession({
  videoId: "01JZ9WV3N8GQ5T2M7K4C6XBARH",
  viewerDisplayText: "Ahmed K.", // shown in the watermark
});

// Send session.sessionToken to the page. Keep the API key on the server.
console.log(session.sessionToken);

2. الصق التضمين في صفحتك

أضِف عنصر التركيب ووسم السكربت حيث يجب أن يظهر الفيديو. يمسح السكربت الصفحة بحثًا عن data-videohati-video-id، ويركّب مشغّلًا على كل تطابق.

<div
  data-videohati-video-id="01JZ9WV3N8GQ5T2M7K4C6XBARH"
  data-videohati-project-id="01JZ9WV3N8GQ5T2M7K4C6XBARP"
  data-videohati-session-token="{{ session token from your server }}"
  data-videohati-lang="ar"
></div>
<script src="https://cdn.videohati.com/player.js" async></script>

استبدل العنصر النائب في data-videohati-session-token بالرمز الذي أنشأه خادمك للتوّ. يرفض المشغّل أن يبدأ من دونه، ويعرض رسالة "رمز الجلسة مفقود" بدلًا من ذلك.

سمات البيانات

اضبط هذه السمات على عنصر التركيب. السمات الثلاث الأولى وحدها إلزامية.

ووردبريس وأنظمة إدارة المحتوى الأخرى

في ووردبريس، أضِف كتلة HTML مخصّص إلى تدوينتك أو صفحتك، ثم الصق عنصر التركيب ووسم السكربت من الخطوة 2. وأي نظام إدارة محتوى يقبل HTML الخام يعمل بالطريقة نفسها.

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

سياسة أمان المحتوى

إذا كان موقعك يرسل ترويسة سياسة أمان المحتوى، فاسمح لأصلَي فيديوهاتي كي يُحمَّل السكربت ويصل إلى الواجهة:

script-src https://cdn.videohati.com;
connect-src https://api.videohati.com https://cdn.videohati.com;
media-src blob:;