> העתק ציבורי של מדריך המפתחים של ViewStream (לקריאה גם על ידי סוכני AI). רשימת המדריכים: https://www.viewstream.co.il/he/developers/guide/index.md · תיעוד ה-API: https://api.viewstream.co.il/docs/

# שילוב הנגן

איך מציבים את הנגן של ViewStream (**Player v2** — ‏Video.js 8 עם הסקינים והתוספים של ViewStream) בעמודים שלכם,
בוחרים תצורת נגן ומאזינים לאירועים שלו.

מקורות: הטוען player/site/embed.js (באנגלית), הנגן
player/site/lab/b/vs-vjs.js (באנגלית), העמודים המתארחים
player/site/_hosted/ (באנגלית), מסמכי התצורה
player-configs.md (באנגלית), ו-player/README.md (באנגלית).

## שלוש דרכים להטמעה

Studio בונה לכם את שלושתן: פתחו ערוץ, קליפ או סרטון והשתמשו ב-**הטמעה ושיתוף** — **קישור לשיתוף**,
**הטמעה (iframe)** ו-**הטמעה (תגית נגן)**.

### 1. קישור שיתוף — עמוד צפייה מתארח

```
https://player.viewstream.co.il/w/<tenant>/<kind>/<id>[?start=<s>&lang=<xx>&config=<name>]
```

`kind` הוא `live` (המזהה = ה-slug של הערוץ), `vod` (המזהה = מזהה הסרטון) או `clip` (המזהה = מזהה הקליפ). העמוד כולל
תגיות תצוגה מקדימה לרשתות חברתיות, כך שהקישור נפתח עם תצוגה מקדימה ב-WhatsApp, ב-Facebook ובאחרות.

### 2. ‏iframe — ההטמעה הפשוטה ביותר

```html
<iframe src="https://player.viewstream.co.il/e/acme/live/main"
        allow="autoplay; fullscreen; picture-in-picture" allowfullscreen
        style="aspect-ratio:16/9;width:100%;border:0"></iframe>
```

אפשרויות שאילתה: `autoplay=1` (מתחיל מושתק), `start=<seconds>` (לא לשידור חי), `lang=he|en|ru|ar`, `config=<name>`.

### 3. תגית נגן — הנגן בתוך העמוד שלכם

```html
<script async src="https://player.viewstream.co.il/embed.js"
        data-src="https://cdn.acme.vustream.net/live/acme/main/master.m3u8"
        data-tenant="acme"
        data-config="news"
        data-lang="he"></script>
```

הנגן מופיע במקום שבו נמצאת התגית (או בתוך `data-target="<css selector>"`). הטוען מושך את כל השאר
(Video.js, סקין, שפה, Chromecast, תמיכה ב-DRM) מ-`player.viewstream.co.il`, פעם אחת לכל עמוד, גם כשיש בעמוד כמה
נגנים.

מאפיינים נפוצים (כולם אופציונליים, חוץ ממקור):

| מאפיין | משמעות |
|---|---|
| `data-src` | כתובת HLS (`.m3u8`), DASH (`.mpd`) או MP4 |
| `data-tenant` | ה-slug של הארגון שלכם; אחרת נלקח מהכתובת (`/live/<tenant>/…`, `/vod/<tenant>/…`, או `?c=<tenant>`) |
| `data-config` | תצורת נגן בעלת שם (ראו בהמשך); ברירת המחדל = התצורה שנקבעה לתוכן |
| `data-skin` | `classic`, `cinema`, `neon`, `glass`, `minimal`, `emoji`, `retro`, או כל אחד מ-100 מזהי הסקינים בספרייה ב-`/skins/` |
| `data-lang` | `he`, `en`, `ru`, `ar` |
| `data-autoplay="1"` + `data-muted="1"` | ניגון אוטומטי (דפדפנים מאפשרים אותו רק במצב מושתק) |
| `data-start`, `data-end` | שניות |
| `data-aspect` | למשל `16:9` |
| `data-width` | רוחב מרבי בפיקסלים |
| `data-resume` | `ask` (ברירת מחדל), `auto`, `off` — המשך מהמקום שבו הצופה עצר (נשמר רק בדפדפן של הצופה) |
| `data-max-seek-back` | שידור חי: כמה שניות הצופה יכול לחזור אחורה מהשידור החי (`0` = שידור חי בלבד) |
| `data-back-to-live="0"` | הסתרת הכפתור לחזרה לשידור החי |
| `data-restart="1"`, `data-restart-back` | כפתור התחלה מחדש בערוצים חיים ללא לוח שידורים |
| `data-cinema="1"` | כפתור מצב קולנוע (במחשב) |
| `data-mode="tile"` | אריח תצוגה מקדימה מושתק במקום נגן מלא |
| `data-options` | JSON לרשימות ולאובייקטים (`sources`, `tracks`, `chapters`, `thumbnails`, `ads`, `drm`, `configDoc`) |

הרשימה המלאה נמצאת בהערה שבראש embed.js (באנגלית) (גרסת טוען 1.3.0).

### שידורים מוגנים

כשמדיניות צפייה דורשת טוקנים, הנגן מבקש בעצמו כתובת חתומה מהמנפיק הציבורי (`POST /v1/playback/session`), ומנפיק
מחדש כשתוקף הטוקן פג. אם אתם חותמים ב-backend שלכם, העבירו את ה-`src` החתום מ-
`POST /v1/playback/tokens` בתור `data-src` ([recipes.md](recipes.md#קבלת-כתובת-צפייה-או-טוקן-חתום)).
‏`embed.allowed_domains` בתצורה מגביל אילו אתרים רשאים להטמיע.

## תצורות נגן

תצורה היא מסמך JSON שעורכים ב-Studio → **נגנים**: סקין, ערכת נושא, שפה, מיתוג ולוגו, פקדים, ברירות מחדל לניגון,
שכבת לוח השידורים בשידור חי, פרסומות, Beacons, הגדרות אריח ודומיינים מורשים.

| כתובת (ציבורית, ללא מפתח, CORS `*`, במטמון 60 שניות, `ETag`) | מה |
|---|---|
| `https://player.viewstream.co.il/player/config/<tenant>.json` | ברירת המחדל של הארגון |
| `https://player.viewstream.co.il/player/config/<tenant>/<name>.json` | תצורה בעלת שם |
| `https://player.viewstream.co.il/player/config/<tenant>/resolve.json?kind=live\|vod\|clip&id=<…>` | התצורה שחלה על התוכן הזה (לפי שיוך: ערוץ → ברירת המחדל לשידור חי → ארגון; סרטון → מדור → ברירת המחדל של הספרייה → ארגון), ובנוסף `resolved_from` ונתוני הכותרת של התוכן |

אותם נתיבים עונים גם ב-`api.viewstream.co.il`. שינוי ב-Studio מגיע לצופים תוך כדקה. ארגוני CDN בלבד ושמות לא
מוכרים מחזירים `404` (ואז הנגן משתמש בברירות המחדל המובנות שלו).

סדר העדיפות בתוך הנגן: מאפיינים בעמוד > מסמך התצורה > ברירות מחדל מובנות.

ניהול תצורות דרך ה-API: `GET/POST /v1/player-configs`, `GET/PATCH/DELETE /v1/player-configs/{id}`
(קריאה `assets:read`, כתיבה `delivery:write`), והיכן הן חלות: `/v1/player-config-assignments`. כל המפתחות
וברירות המחדל: player-configs.md (באנגלית).

## אירועים

האזינו על תיבת הנגן (האלמנט שבו הוצב הנגן, או כל אב שלו — האירועים מבעבעים למעלה):

| אירוע DOM | `detail` | מתי |
|---|---|---|
| `vs:ready` | `{player, engine}` (`engine` הוא `b` = Player v2, או `tile`) | הנגן נוצר |
| `vs:error` | `{error}` | הטוען נכשל (JSON שגוי ב-`data-options`, יעד חסר, קובץ שלא נטען) |
| `vs:config` | `{theme, config}` | התצורה שנקבעה הוחלה — עצבו את העמוד שלכם לפיה |
| `vs:cinema` | `{on}` | מצב קולנוע הופעל או כובה (העמוד שלכם מסדר את עצמו; או עצבו את `html.vs-cinema-on`) |

```html
<script>
document.addEventListener('vs:ready', function (e) {
  var player = e.detail.player;          // a Video.js player
  player.on('vsqualitychange', function () { /* … */ });
  player.on('vsdeny', function (ev) { console.log('denied', ev); });
});
</script>
```

`e.detail.player` הוא נגן Video.js: כל אירועי Video.js הרגילים (`play`, `pause`, `ended`, `timeupdate`, …) עובדים.
ViewStream מוסיף, בין השאר: `vsqualitychange`, `vscaptionchange`, `vsskinchange`, `vsthemechange`, `vscast`,
`vsstatschange`, `vsmenuopen`, `vsdeny` (ה-CDN סירב לניגון — טוקן, גאו, החשכה…), `vstokenrefresh`,
`vsreconnect`, `vsstallskip`, `vspathway` (מעבר בין CDNs ‏`{from, to, reason}`), `vsdrmunavailable`, ואירועי
הפרסומות `adstart`, `adend`, `adskip`, `adclick`, `quartile`. השמות האלה לקוחים מהקוד
(vs-vjs.js (באנגלית)); המטען (payload) שלהם עדיין אינו חוזה קבוע.

`window.VSEmbed` מחזיק `{version, players}` לכל נגן שהטוען יצר בעמוד.

## סטטיסטיקות צפייה (Beacons)

הנגן מדווח על צפייה אל `https://<your cdn_hostname>/b/v1` (fetch עם keep-alive, ו-`sendBeacon` ביציאה מהעמוד) כאשר
`beacon.enabled` בתצורה פעיל (ברירת מחדל); פעימה (heartbeat) כל `beacon.heartbeat_s` שניות (5–120, ברירת מחדל 15)
(vs-beacon.js (באנגלית)). ה-Beacons האלה מזינים את Studio → אנליטיקה ואת
ה-API ‏`/v1/stats`. נעשה שימוש רק במזהה צופה אנונימי מגובב, ורק בהסכמה.

## Sites SDK ורכיבי web

לאריחים, לפסים ולאלמנט `<vs-player>` באתר שלכם: `@viewstream/sites-wc` בכתובת
`https://player.viewstream.co.il/sdk/sites-wc@0.2.4.js` (הדגמה `/sdk/demo.html`, תיעוד
studio/packages/sites-wc/README.md (באנגלית)). הוא קורא את
[Sites Delivery API](sites-delivery-api.md).

## מצב תכונות הנגן

| תכונה | מצב |
|---|---|
| שידור חי HLS / LL-HLS, ‏DVR, צפייה מההתחלה, צפייה חוזרת, שכבת לוח שידורים | פעיל |
| פרסומות בצד הלקוח (VAST/VMAP, מנוע פנימי או IMA), פרה-רול של הבית | פעיל |
| פרסומות בצד השרת (SSAI) | נבנה, **כבוי כברירת מחדל** (מתג פלטפורמה) |
| VOD מוצפן ב-AES-128 | פעיל |
| ‏DRM של FairPlay / Widevine | **ממתין** — דורש חשבון אצל ספק ה-DRM (דוח עבודה §54) |
| Chromecast | פעיל (דפדפני Chromium, לא iOS) |