Általános leírás fejlesztőknek

A Videa három alkalmazásprogramozási felületet (API-t) biztosít fejlesztők számára.
A háromból kettő (PlayerAPI és OpenAPI) regisztráció után mindenki számára szabadon elérhető. A harmadik (PartnerAPI) csak szerződött partnerek számára hozzáférhető.

PlayerAPI

Tetszőleges oldalba beágyazott Videa lejátszó vezérlésére és állapotának lekérdezésére szolgál.
A PlayerAPI segítségével létre tudunk hozni saját arculattal rendelkező videólejátszót, vagy az oldalunk működését tudjuk befolyásolni a videólejátszás állapotától függően.
OpenAPI

Videára feltöltött videók adatait tudjuk az OpenAPI segítségével kiolvasni. Ezeket az adatokat tetszőlegesen jeleníthetjük meg az oldalunkon.
PartnerAPI

Videa csatornatulajdonosok a PartnerAPI használatával tudnak videót feltölteni, korábban feltöltött videók adatait módosítani és azokat törölni.

A Videa három alkalmazásprogramozási felületével kapcsolatos kérdéseket, észrevételeket a devsupport@videa.hu e-mail címre várjuk.

Bevezető
Előfeltételek
Beépítési példa
Videa PlayerAPI betöltése
Videa Player létrehozása
PlayerAPI beágyazó kóddal
Beágyazó kód megadása
API használatba vétele
Működés
Funkciók
Eseménykezelők
- onReady
- onKeyError
További példák
Dokumentum verziók

PlayerAPI

Bevezető

A PlayerAPI használatával az oldalba beágyazott Videa-lejátszókat lehet vezérelni JavaScript hívásokkal. Az API metódusaival videót tölthetünk a lejátszóba, elindíthatjuk, megállíthatjuk a lejátszást, beletekerhetünk a videóba, állíthatjuk a hangerőt, illetve lekérdezhetjük a lejátszó pillanatnyi állapotát. Kikapcsolhatjuk a lejátszó felhasználói felületét (gombok, vezérlősáv), és helyettesíthetjük azt saját arculatot képviselő vezérlőelemekkel. Befolyásolhatjuk az oldalunk viselkedését, megjelenését a lejátszás állapotától függően. Az API eseménykezelői segítségével értesülhetünk a lejátszó állapotában bekövetkező változásokról. A PlayerAPI-t regisztráció után mindenki szabadon használhatja.

Előfeltételek

A PlayerAPI használatához a HTML5 postMessage lehetőséget támogató böngészőre van szükség. Ezt a feltételt a mai modern böngészők nagy többsége (Chrome, Firefox, Safari, Opera) teljesíti, az Internet Explorer a 10-es változat előtt az API által használt funkcionalitást nem valósítja meg.

A PlayerAPI használatához a https://videa.hu/static/api/player_api_v1.0.3.js címen elérhető JavaScript fájlt kell beilleszteni az oldalba, és a beillesztéshez két paramétert kell megadnunk, egy API kulcsot és egy visszahívási (callback) függvényt:

<script async defer type="text/javascript"
  src="https://videa.hu/static/api/player_api_v1.0.3.js?key=API_KULCS&callback=CALLBACK">
</script>

API kulcsot belépés után a BEÁLLÍTÁSAIM menüpont alatt található űrlapon kell kérni. A kulcs mellett meg kell adni annak/azoknak a webhely(ek)nak a címét is, amelyeken az API működését engedélyezni szeretnénk.

A visszahívási (callback) függvényt az oldal kódjának tartalmaznia kell.

A beágyazott Videa lejátszó minimális szélessége 200px, minimális magassága pedig 113px. Az ajánlott méret, aminél kezelőfelület minden alkotóeleme megjeleníthető a szélesség 356px, a magasság 200px.

Példa

Az alábbi beépítési példa egy egyszerű működést demonstrál.


<!DOCTYPE html>
<html>
  <head>
    <title>PlayerAPI</title>
    <!-- a head részbe kerül az PlayerAPI javascript betöltése,
         itt kell megadni az egyedi API kulcsot és a visszahívási függvényt is -->
    <script async defer type="text/javascript"
      src="https://videa.hu/static/api/player_api_v1.0.3.js?key=1234567890ABCDE&callback=videaPlayerAPILoaded">
    </script>
  </head>
  <body>
    <!-- ennek az elemnek a helyére fog betöltődni a Videa lejátszó -->
    <div id="player_div"></div>
    <script type="text/javascript">

      <!-- ez a változó tartalmazza majd a létrejött Videa lejátszó objektumot -->
      var videaPlayer;

      <!-- ez a kód hozza létre a Videa lejátszót, a paraméterekről részletesen a dokumentumban később -->
      function videaPlayerAPILoaded() {
        videaPlayer = new VIDEA.VideaPlayer({
          divToLoad: "player_div",
          width: "480",
          height: "360",
          videoId: "G5qkVOjzYbKaF0zZ",
          events: {
            "onReady": onPlayerReady,
            "onKeyError": onApiKeyError
          }
        });
      }

      <!-- a PlayerAPI az onReady esemény esetén hívja meg ezt a függvényt -->
      function onPlayerReady(target) {
        target.playVideo();
      }

      <!-- a PlayerAPI az onKeyError esemény esetén hívja meg ezt a függvényt -->
      function onApiKeyError(target) {
        console.log("Hibás API kulcs!");
      }

      function leallitas() {
        videaPlayer.stopVideo();
      }

    </script>
  </body>
</html>

Videa PlayerAPI betöltése

Az oldal kódjában - lehetőleg a head részben - be kell tölteni a PlayerAPI-t.

<script async defer type="text/javascript"
  src="https://videa.hu/static/api/player_api_v1.0.3.js?key=1234567890ABCDE&callback=videaPlayerAPILoaded">
</script>

A betöltésnél két paramétert kell megadni:

key - ez a felhasználó egyedi API kulcsa, amit a BEÁLLÍTÁSAIM oldalon láthat, ha pedig még nem rendelkezik ilyen kulccsal, akkor ugyanott tud új kulcsot létrehozni. Fontos, hogy a BEÁLLÍTÁSAIM oldalon meg kell adni annak/azoknak a webhely(ek)nak a címét is, amelyeken az API működését engedélyezni szeretnénk.
callback - amikor az API már rendelkezésre áll, ez a függvény kerül meghívásra.

Videa Player létrehozása

A Videa lejátszó létrehozásánál meg kell adni azt a HTML elemet, amelynek a helyére a lejátszó létrejön:


<div id="player_div"></div>

Az elem egyedi azonosítóját (id) kell megadni a lejátszó létrehozásánál.

A Videa lejátszó létrehozása előtt létre lehet hozni egy változót, amely majd a létrehozott videaPlayer objektumot tartalmazza:


var videaPlayer;

A Videa lejátszó létrehozását a PlayerAPI betöltésénél megadott visszahívási függvényben kell kezdeményezni. A Videa lejátszó a következő kóddal jön létre:


function videaPlayerAPILoaded() {
  videaPlayer = new VIDEA.VideaPlayer({
    divToLoad: "player_div",
    width: "480",
    height: "360",
    videoId: "G5qkVOjzYbKaF0zZ",
    events: {
      "onReady": onPlayerReady,
      "onKeyError": onApiKeyError
    }
  });
}

A Videa lejátszó létrehozásál átadott objektum elemei:

divToLoad - itt kell megadni annak a HTML elemnek az azonosítóját (id), amelynek a helyére a lejátszó létrejön.
width - a lejátszó szélessége.
height - a lejátszó magassága.
videoID - a betölteni kívánt videó egyedi azonosítója (a Videa lejátszóoldal címének utolsó 16 karaktere).
events - itt kell felsorolni azokat az eseménykezelőket, amelyeknek az általunk fontosnak tartott eseményekre reagálnak. Az eseményekről részletesen a dokumentum további részében olvashatsz. Fontos, hogy az itt felsorolt eseménykezelő függvényeket az oldal kódjának tartalmaznia kell.

PlayerAPI használata beágyazó kóddal

Lehetőség van úgy is a PlayerAPI használatára, ha a Videa lejátszó beágyazó kódját helyezzük el az oldalban néhány beágyazási paraméterrel kiegészítve. Ezt mutatja az alábbi példa.


<!DOCTYPE html>
<html>
  <head>
    <title>PlayerAPI</title>
    <!-- a head részbe kerül az PlayerAPI javascript betöltése,
         itt kell megadni az egyedi API kulcsot és a visszahívási függvényt is -->
    <script async defer type="text/javascript"
      src="https://videa.hu/static/api/player_api_v1.0.3.js?key=1234567890ABCDE&callback=videaPlayerAPILoaded">
    </script>
  </head>
  <body>
    <!-- videó beágyazása a Videa beágyazó kódjával, a szükséges paraméterekkel kiegészítve -->
    <iframe id="videa_player_iframe" width="480" height="360"
      src="https://videa.hu/player?v=vz3m8CU4UG3OcXMK&enableJsApi=1&apiKey=1234567890ABCDE"
      allowfullscreen="allowfullscreen" webkitallowfullscreen="webkitallowfullscreen"
      mozallowfullscreen="mozallowfullscreen" frameborder="0"></iframe>

    <script type="text/javascript">

      <!-- ez a változó tartalmazza majd a létrejött Videa lejátszó objektumot -->
      var videaPlayer;

      <!-- ez a kód hozza létre a Videa lejátszót, a paraméterekről részletesen a dokumentumban később -->
      function videaPlayerAPILoaded(){
        videaPlayer= new VIDEA.VideaPlayer({
          iframeID: "videa_player_iframe",
          events: {
            "onReady": onPlayerReady,
            "onKeyError": onApiKeyError
          }
        });
      }

      <!-- a PlayerAPI az onReady esemény esetén hívja meg ezt a függvényt -->
      function onPlayerReady(target) {
        target.playVideo();
      }

      <!-- a PlayerAPI az onKeyError esemény esetén hívja meg ezt a függvényt -->
      function onApiKeyError(target) {
        console.log("Hibás API kulcs!");
      }

      function leallitas() {
        videaPlayer.stopVideo();
      }

    </script>
  </body>
</html>

Beágyazó kód megadása

A Videa lejátszóoldaláról kimásolható beágyazó kód felhasználásával is beépíthetjük oldalunkba a lejátszót, amelyet a későbbiekben a PlayerAPI használatával kívánunk vezérelni.


    <iframe id="videa_player_iframe" width="480" height="360"
      src="https://videa.hu/player?v=vz3m8CU4UG3OcXMK&enableJsApi=1&apiKey=1234567890ABCDE"
      allowfullscreen="allowfullscreen" webkitallowfullscreen="webkitallowfullscreen"
      mozallowfullscreen="mozallowfullscreen" frameborder="0"></iframe>

A fent látható példa a kimásolt beágyazó kódot három ponton egészíti ki:

id attribútum - az iframe elemnek adnunk kell egy "id" attribútumot, amelynek az értékét (a példában: "videa_player_iframe") a lejátszó objektum létrehozásánál meg kell majd adnunk.
enableJsApi paraméter - az iframe elem "src" attribútumában szereplő url értékét ki kell egészítenünk az "&enableJsApi=1" paraméterrel.
apiKey paraméter - az iframe elem "src" attribútumában szereplő url értékét ki kell egészítenünk az "&apiKey=1234567890ABCDE" paraméterrel, ahol az "1234567890ABCDE" értéket saját API kulcsunk értékével kell helyettesíteni.

API használatba vétele beágyazó kód esetén

A playerAPI használatba vétele előtt létre lehet hozni egy változót, amelyen keresztül a beágyazó kóddal megadott playert vezéreljük majd:


var videaPlayer;

A hozzáférést a beágyazó kóddal megadott lejátszóhoz a PlayerAPI betöltésénél megadott visszahívási függvényben kell kezdeményezni:


function videaPlayerAPILoaded(){
  videaPlayer= new VIDEA.VideaPlayer({
    iframeID: "videa_player_iframe",
    events: {
      "onReady": onPlayerReady,
      "onKeyError": onApiKeyError
    }
  });
}

A Videa lejátszó létrehozásál átadott objektum elemei:

iframeID - itt kell megadni a beágyazó kódhoz rendelt egyedi azonosítót (id).
events - itt kell felsorolni azokat az eseménykezelőket, amelyeknek az általunk fontosnak tartott eseményekre reagálnak. Az eseményekről részletesen a dokumentum további részében olvashatsz. Fontos, hogy az itt felsorolt eseménykezelő függvényeket az oldal kódjának tartalmaznia kell.

Működés

A PlayerAPI függvényeinek meghívásánál minden esetben szükség van a Videa lejátszó vezérlő objektumra. Ez az objektum a dokumentumban korábban szereplő két beépítési példában leírt módon jön létre.

Funkciók

playVideo

A playVideo hívás a videólejátszást indítja el, akár a lejátszó betöltődése után első alkalommal, akár a lejátszás közbeni megállítást követően (pauseVideo), akár új videó betöltését követően (loadVideo).

pauseVideo

Ha a videó lejátszása folyamatban van, a pauseVideo hívás a lejátszást megállítja anélkül, hogy a lejátszás pillanatnyi pozícióját megőrizve. A pauseVideo hívás után a lejátszás a playVideo hívással indítható újra.

isPlaying

Az isPlaying hívással lekérdezhetjük, hogy folyamatban van-e éppen a lejátszóban a videó lejátszása. Visszatérési értéke 0, ha a lejátszás áll, 1, ha folyamatban van.

seekTo(sec)

A seekTo hívással megváltoztathatjuk a lejátszás pozícióját (beletekerhetünk a videóba). A hívás paramétere egy szám, amely másodpercben fejezi ki a pozíciót, ahová a lejátszófejet állítani kívánjuk (a 138-as érték a videó 3. percének 18. másodpercére ugrik).

getCurrentTime

A getCurrentTime hívás visszaadja a pillanatnyi lejátszási pozíciót, másodpercben.

getDuration

A getDuration hívással lekérdezhetjük, milyen hosszú a lejátszóban látható videó, másodpercben kifejezve.

getVersions

A getVersions hívással lekérdezhetjük, hogy a lejátszóban látható videóból milyen, különböző minőségű/felbontású változatok állnak rendelkezésére. A visszaadott érték egy tömb, amelynek egy-egy elemében a különböző változatok neve (pl. "720p") és felbontása (szélesség, magasság) szerepel:

[
  {"name": "240p", "width":426, "height":240},
  {"name": "360p", "width":640, "height":360},
  {"name": "480p", "width":852, "height":480}
]

getSelectedVersion

A getSelectedVersion hívással lekérdezhetjük, hogy a videó rendelkezésre álló, különböző minőségű/felbontású változatai közül a lejátszóban melyik látható éppen. A visszaadott érték a minőségre utaló név (pl. "720p").

changeVersion(name)

A changeVersion hívással utasíthatjuk a lejátszót a megadott névvel (pl. "720p") jellemzett minőség betöltésére, mutatására. A szóba jöhető nevek halmazát a getVersions hívás árulja el.

mute

A mute hívással némíthatjuk a hangerőt a lejátszóban.

unMute

Az unMute hívással visszakapcsolhatjuk a hangot a korábban némított lejátszóban.

getVolume

A getVolume hívással lekérdezhetjük a hangerőszabályozó pillanatnyi állását a lejátszóban. A visszaadott érték 0 és 100 közötti, százalékos értékként értelmezendő szám, ahol a teljes hangerőt a 100, a némára állítottat a 0 jelenti.

setVolume(n)

A setVolume hívással beállíthatjuk a hangerőt a lejátszóban. A paraméter 0 és 100 közötti, százalékos értékként értelmezendő szám, ahol a teljes hangerőt a 100, a némára állítottat a 0 jelenti.

enableAutoplayNext

Az enableAutoplayNext hívással engedélyezhetjük a lejátszó számára, hogy a betöltött videó lejátszását követően újabb videót töltsön le és játsszon le, automatikusan.

disableAutoplayNext

A disableAutoplayNext hívással megakadályozhatjuk, hogy a lejátszó a betöltött videó lejátszását követően újabb videót töltsön le és játsszon le, automatikusan.

getFullscreenMode

A getFullscreenMode hívással lekérdezhetjük, hogy a lejátszó éppen teljes képernyős módban működik-e. A visszatérési érték 1, ha igen, 0, ha nem.

requestFullscreen

A requestFullscreen hívással teljes képernyős módba kapcsolhatjuk a lejátszót. A böngészők által alkalmazott biztonsági korlátozások miatt a hívás csak felhasználói kezdeményezésre (pl. kattintás) hajtható végre.

cancelFullscreen

A requestFullscreen hívással visszakapcsolhatjuk teljes képernyős módból normál módba a lejátszót.

enablePlayerUI

Az enablePlayerUI hívással bekapcsolhatjuk a lejátszó saját kezelőfelületét (gombor, vezérlősáv, záróképernyő stb.).

disablePlayerUI

A disablePlayerUI hívással kikapcsolhatjuk a lejátszó saját kezelőfelületét (gombor, vezérlősáv, záróképernyő stb.). Ekkor a felhasználó a lejátszó működését nem tudja befolyásolni, hacsak nem biztosítunk számára, a lejátszót a PlayerAPI-n keresztül irányító kezelőszerveket oldalunkon.

getVideoTitle

A getVideoTitle hívással lekérdezhetjük a lejátszóban éppen látható videó címét.

getVideoID

A getVideoID hívással lekérdezhetjük a lejátszóban éppen látható videó 16 karakteres azonosítóját.

getVideoUrl

A getVideoUrl hívással lekérdezhetjük a lejátszóban éppen látható videó saját, videás oldalának a címét.

loadVideo(videoID)

A loadVideo hívással új videót tölthetünk be a lejátszóba a 16 karakteres videóazonosító megadásával. Betöltést követően a lejátszás nem indul el automatikusan.

loadAndStartVideo(videoID)

A loadAndStartVideo hívással új videót tölthetünk be a lejátszóba a 16 karakteres videóazonosító megadásával. Betöltést követően a lejátszás automatikusan elindul.

Eseménykezelők

Miután létrehoztuk a Videa lejátszót vezérlő JavaScript objektumunkat, kétféle esemény kezelésére kell felkészülnünk, és az egyes eseményekhez a létrehozáskor eseménykezelő függvényeket megadnunk, amennyiben úgy látjuk jónak.

onReady

Az onReady eseménykezelővel arra az eseményre reagálhatunk, amely akkor következik be, amikor a Videa lejátszó készen áll a vezérlőobjektumon keresztül kiadott utasításokat elfogadni. Az eseménykezelő paramétere maga a vezérlőobjektum, így egy oldalon több lejátszót is használhatunk úgy, hogy mindegyiknek ugyanazt az eseménykezelő függvényt adjuk meg létrehozáskor.

onKeyError

Az onKeyError eseménykezelővel arra az esetre készülhetünk fel, ha hibás API kulcsot adtunk meg a Videa PlayerAPI betöltésekor, vagy ha olyan webhelyről próbáljuk az API-t használni, amelyet nem engedélyeztünk korábban az API kulcs beállításai között.

Példa több lejátszó vezérlésére egy oldalon

Ha több lejátszót szeretnénk egy oldalra.


<!DOCTYPE html>
<html>
  <head>
    <title>PlayerAPI</title>
    <script async defer type="text/javascript" src="https://videa.hu/static/api/player_api_v1.0.3.js?key=505806029628277&callback=videaPlayerAPILoaded"></script>
  </head>
  <body>
    <div id="player_div"></div>
    <iframe id="videa_player_iframe" width="480" height="360"
     src="https://videa.hu/player?v=vz3m8CU4UG3OcXMK&enableJsApi=1&apiKey=505806029628277"
     allowfullscreen="allowfullscreen" webkitallowfullscreen="webkitallowfullscreen"
     mozallowfullscreen="mozallowfullscreen" frameborder="0"></iframe>


    <script type="text/javascript">

      var videaPlayer;
      var videaPlayerIframe;
      function videaPlayerAPILoaded(){
        videaPlayer = new VIDEA.VideaPlayer({
          divToLoad: "player_div",
          width: "480",
          height: "360",
          videoId: "G5qkVOjzYbKaF0zZ",
          events: {
            "onReady": onPlayerReady,
            "onKeyError": onApiKeyError
          }
        });
        videaPlayerIframe = new VIDEA.VideaPlayer({
          iframeID: "videa_player_iframe",
          events: {
            "onReady": onPlayerReady,
            "onKeyError": onApiKeyError
          }
        });
      };

      function onPlayerReady(target) {
        target.playVideo();
      }

      function onApiKeyError(target) {
        console.log("Hibás API kulcs!");
      }

      function leallitasEgyik(){
        videaPlayer.stopVideo();
      }

      function leallitasMasik(){
        videaPlayerIframe.stopVideo();
      }

    </script>
  </body>
</html>

Dokumentum verziók

2017. október 1.

Első publikus verzió

Bevezető
Előfeltételek
Beépítési példa
Videa OpenAPI betöltése
OpenAPI vezérlőobjektum létrehozása
OpenAPI vezérlőobjektum használata
Működés
Funkciók
Hibakezelés
Dokumentum verziók

OpenAPI

Bevezető

A Videa OpenAPI segítségével saját weboldalunkban jeleníthetünk meg a Videáról származó tartalmakat (keresések eredményét, egy kategóriába, csatornába, feltöltő felhasználóhoz tartozó videók listáját, egy adott videó adatait) egyszerű JavaScript hívásokkal.

Előfeltételek

A Videa OpenAPI használatához a JavaScript Promise objektumot ismerő böngésző szükséges (Firefox 29-től, Chrome 33-tól, Safari 7.1-től, Opera 20-tól, Microsoft Edge 12-től). Az Internet Explorer egyetlen verziója sem ismeri ezt a nyelvi elemet.

Az OpenAPI használatához a https://videa.hu/static/api/open_api_v1.0.1.js címen elérhető JavaScript fájlt kell beilleszteni az oldalba, és a beillesztéshez két paramétert kell megadnunk, egy API kulcsot és egy visszahívási (callback) függvényt:

<script async defer type="text/javascript"
  src="https://videa.hu/static/api/open_api_v1.0.1.js?key=API_KULCS&callback=CALLBACK">
</script>

A visszahívási (callback) függvényt az oldal kódjának tartalmaznia kell.

Példa

Az alábbi beépítési példa egy egyszerű működést demonstrál.

<!DOCTYPE html>
<html>
  <head>
    <title>OpenAPI</title>
    <!-- a head részbe kerül az OpenAPI javascript betöltése,
         itt kell megadni az egyedi API kulcsot és a visszahívási függvényt is -->
    <script async defer type="text/javascript"
      src="https://videa.hu/static/api/open_api_v1.0.1.js?key=1234567890ABCDE&callback=videaOpenAPILoaded">
    </script>
  </head>
  <body>
    <!-- ebben az elemben fogjuk felsorolni a lekért videók listáját -->
    <div id="video_list"></div>
    <!-- ebbe az elembe fogunk betölteni egy Videa lejátszót -->
    <div id="player_div"></div>
    <!-- ebbe az elembe fogjuk beleírni a lejátszóban látható videó címét -->
    <div id="video_title"></div>
    <script type="text/javascript">

      <!-- ez a változó tartalmazza majd a létrejött Videa OpenAPI objektumot -->
      var videa;

      <!-- a visszahívási (callback) függvény  -->
      function videaOpenAPILoaded() {
        <!-- létrehozzuk a Videa OpenAPI objektumot  -->
        videa = new VIDEA.VideaOpenAPI();
        <!-- lekérjük a "kardhal" címkéhez tartozó videókat -->
        videa.getTagVideos("kardhal", "upload_date", 1).then(function(response) {
          <!-- siker esetén a videók címét kattintható linkként betöltjük az erre szánt HTML elembe -->
          var video_list_container = document.getElementById("video_list");
          video_list_container.innerHTML = "<b>kardhal címke videók</b><br>";
          for (i=0; i<response.videos.length; i++) {
            video_list_container.innerHTML += "<a href=\"javascript:loadVideo('"
             + response.videos[i].vcode
             + "')\">"
             + response.videos[i].title
             + "</a><br>";
          }
          video_list_container.innerHTML += "<br>";
        }, function(error) {
          <!-- hiba esetén kiírjuk a hibaüzenetet a JavaScript console-ra  -->
          console.error(error);
        });
      }

      <!-- a listaelemekre kattintva ez a függvény fut le -->
      function loadVideo(videoId) {
        <!-- lekérjük egy videó adatait az API-n -->
        videa.getVideoData(videoId, 0, 576).then(function(response) {
          <!-- siker esetén beleírjük a visszakapott adatok közül a beágyazó kódot az erre szánt HTML elembe  -->
          document.getElementById("player_div").innerHTML = response.oembed_data.html;
          <!-- és beleírjük a visszakapott adatok közül a videó címét a megfelelő HTML elembe  -->
          document.getElementById("video_title").innerText = response.title;
        }, function(error) {
          <!-- hiba esetén kiírjuk a hibaüzenetet a JavaScript console-ra  -->
          console.error(error);
        });
      }

    </script>
  </body>
</html>

Videa OpenAPI betöltése

Az oldal kódjában - lehetőleg a head részben - be kell tölteni az OpenAPI-t.

<script async defer type="text/javascript"
  src="https://videa.hu/static/api/open_api_v1.0.1.js?key=1234567890ABCDE&callback=videaOpenAPILoaded">
</script>

A betöltésnél két paramétert kell megadni:

key - ez a felhasználó egyedi API kulcsa, amit a BEÁLLÍTÁSAIM oldalon láthat, ha pedig még nem rendelkezik ilyen kulccsal, akkor ugyanott tud új kulcsot létrehozni. Fontos, hogy a BEÁLLÍTÁSAIM oldalon meg kell adni annak/azoknak a webhely(ek)nak a címét is, amelyeken az API működését engedélyezni szeretnénk.
callback - amikor az API már rendelkezésre áll, ez a függvény kerül meghívásra.

OpenAPI vezérlőobjektum létrehozása

A Videa OpenAPI vezérlőobjektumot a visszahívási (callback) függvény hozza létre. Az objektum számára létrehozhatunk előre egy változót:

var videa;

A Videa OpenAPI vezérlőobjektum létrehozását az OpenAPI betöltésénél megadott visszahívási függvényben kell kezdeményezni. Az objektum a következő kóddal jön létre:

function videaOpenAPILoaded() {
  videa = new VIDEA.VideaOpenAPI();
}

OpenAPI vezérlőobjektum használata

A Videa OpenAPI-t arra használjuk, hogy a Videáról származó tartalmakat jelenítsünk meg az oldalunkban. Ezt előkészíthetjük egy (vagy több) olyan HTML elem létrehozásával, amely(ek)be ez(eke)t a tartalma(ka)t be fogjuk tölteni:

<div id="video_list"></div>

A Videa OpenAPI vezérlőobjektum létrehozását követően rajta keresztül kérhetünk adatokat a Videától, amelyekhez a JavaScript Promise objektuma által biztosított szintaxissal férhetünk hozzá:

videa.getTagVideos("kardhal", "upload_date", 1).then(function(response) {
  var video_list_container = document.getElementById("video_list");
  video_list_container.innerHTML = "<b>kardhal címke videók</b><br>";
  for (i=0; i<response.videos.length; i++) {
    video_list_container.innerHTML += "<a href=\"javascript:loadVideo('"
      + response.videos[i].vcode
      + "')\">"
      + response.videos[i].title
      + "</a><br>";
  }
  video_list_container.innerHTML += "<br>";
}, function(error) {
  console.error(error);
});

Működés

A Videa OpenAPI műveleteinek meghívásánál minden esetben szükség van a Videa OpenAPI vezérlőobjektumra. Ez az objektum a dokumentumban korábban leírt módon jön létre, és egy JavaScript változóban tárolhatjuk, amelyen keresztül az OpenAPI adatkérő műveleteit meghívhatjuk. Minden hívás egy JavaScript Promise objektumot ad vissza, amely egy-egy feldolgozó függvény megadását várja a sikeres (resolve) és a sikertelen (reject) lefutás esetére:

videa.searchVideos("batman", 5).then(function(response) {
  // a keresés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A Videa OpenAPI az adatokat JavaScript objektumként adja vissza, a dokumentum a későbbiekben tartalmazza az egyes válaszok formátumának JSON jelölés szerinti leírását.

Funkciók

getVideoData(videoId, maxWidth, maxHeight)

A getVideoData hívás egy videó adatait és a hozzá tartozó beágyazó kódot adja vissza.

videa.getVideoData("zsvvv9x4J0lTzBUT", 0, 576).then(function(response) {
  // a lekérés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A hívás paraméterei:

videoId - a lekérdezendő videó 16 karakteres azonosítója, amely kiolvasható például a videó lejátszóoldalának url-jéből (ez a cím utolsó 16 karaktere), vagy a Videa OpenAPI további hívásainak (pl. keresés) eredményéből.
maxWidth - a válaszban kapott beágyazó kód maximális szélessége, vagy - ha a maxHeight paraméter értékének 0-t adunk meg - a szélessége. Értéke lehet 0 is, ebben az esetben a maxHeight paraméter értéke határozza meg a videólejátszó méretét.
maxHeight - a válaszban kapott beágyazó kód maximális magassága, vagy - ha a maxWidth paraméter értékének 0-t adunk meg - a magassága. Értéke lehet 0 is, ebben az esetben a maxWidth paraméter értéke határozza meg a videólejátszó méretét.

A válasz formátuma:

{
  "cmd":"video_data",
  "vcode":"zsvvv9x4J0lTzBUT",
  "title":"Batman és Robin - előzetes",
  "description":"",
  "tags": [
    {"tid":"9592","tag":"batman"},
    {"tid":"9595","tag":"robin"}
  ],
  "duration":"02:20",
  "upload_date":"2012.06.22.",
  "uploader": {
    "id":"298",
    "disp_name":"videók",
    "type":"subchannel"
  },
  "category": {
    "id":"13",
    "name":"film/animáció"
  },
  "channel": {
    "id":"97",
    "name":"Filmklub"
  },
  "subchannel": {
    "id":"298",
    "name":"videók"
  },
  "thumbnail":"https://videa.hu/static/thumbnail_xl/1.13.2.770582.70299.3",
  "still":"https://videa.hu/static/still/1.13.2.770582.70299.3",
  "oembed_url":"https://videa.hu/oembed/?url=http%3A%2F%2Fvidea.hu%2Fvideok%2Ffilmklub%2Ffilm-animacio%2Fbatman-es-robin-elozetes-zsvvv9x4J0lTzBUT&format=json&maxheight=576",
  "view_count":"0",
  "share_count":"0",
  "send_count":"0",
  "embed_count":"0",
  "oembed_data": {
    "type":"video",
    "version":"1.0",
    "title":"Batman és Robin - előzetes",
    "author_name":"Filmklub",
    "author_url":"https://videa.hu/tagok/filmklub-70299",
    "provider_name":"videa.hu",
    "provider_url":"https://videa.hu",
    "cache_age":86400,
    "thumbnail_url":"https://videa.hu/static/thumbnail_xl/1.13.2.770582.70299.3",
    "thumbnail_width":160,
    "thumbnail_height":120,
    "html":"<iframe width=\"1024\" height=\"576\" src=\"https://videa.hu/player?v=zsvvv9x4J0lTzBUT\" allowfullscreen=\"allowfullscreen\" webkitallowfullscreen=\"webkitallowfullscreen\" mozallowfullscreen=\"mozallowfullscreen\" frameborder=\"0\"></iframe>",
    "width":1024,
    "height":576
  }
}

A válaszban szereplő adatok közül a vcode megegyezik a paraméterkénet átadott videoId értékével, a title a videó címét tartalmazza, a tags tömbben a videóhoz megadott címkéket találjuk azonosítójukkal együtt, ugyanígy a feltöltő (uploader), a kategória (category), opcionálisan a csatorna (channel) és azon belül a rovat (subchannel) adatait is megtaláljuk, kapunk statisztikai adatokat (pl. a nézettség - view_count), alapértelmezett bélyegképet (thumbnail) és teljes méretű állóképet (still) a videóból, végül a videó beágyazásához szükséges adatokat (oembed_data.html). A feltöltő, a címkék, a kategória és a csatorna adatait felhasználhatjuk a későbbiekben a megfelelő videólisták lekérdezéséhez.

getProfileData(userId)

A getProfileData hívás egy felhasználó adatait adja vissza numerikus azonosítója (userId) alapján.

videa.getProfileData(1).then(function(response) {
  // a lekérés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A hívás paraméterei:

userId - a lekérdezendő felhasználó numerikus azonosítója. A felhasználó numerikus azonosítóját megkapjuk például az általa feltöltött videókra vonatkozó getVideoData hívásra kapott válaszban.

A válasz formátuma:

{
  "cmd":"profile_data",
  "uid":"1",
  "reg_date":"2016-01-14",
  "disp_name":"kovacs janos",
  "weburl":"https://www.kovacs.janos",
  "webtitle":"Kovács János weboldala",
  "blogurl":"https://blog.kovacs.janos",
  "blogtitle":"Kovács János okos blogja",
  "facebook_profile_url":"https://www.facebook.com/kovacs.nemisjanos",
  "video_count":"80",
  "view_count":"1670",
  "share_count":"5",
  "send_count":"15",
  "embed_count":"5",
  "avatar_url":"https://videa.hu/static/avatar/3.2.2"
}

A válaszban szereplő adatok közül az uid megegyezik a paraméterkénet átadott userId értékével, a reg_date a regisztráció dátumát, a disp_name a felhasználó által választott megjeleníett nevet tartalmazza, szerepelhet a válaszban saját weboldal, blog és Facebook profiloldal elérhetősége, összesített statisztikai adatok a felhasználó által feltöltött videókra vonatkozólag, és, amennyiben a profil tulajdonosa feltöltött ilyet, egy őt jelképező avatar-ra mutató url.

searchVideos(query, page)

A searchVideos hívás a megadott keresőkifejezésre elvégzett keresés eredményét adja vissza.

videa.searchVideos("batman", 1).then(function(response) {
  // a lekérés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A hívás paraméterei:

query - a keresőkifejezés.
page - a találatok hányadik oldalát kérjük, amennyiben egy oldalnyinál (10 db) több találat van.

A válasz formátuma:

{
  "cmd":"search",
  "offset":0,
  "hits":10,
  "totalhits":106,
  "videos": [
    { ... video1  ...},
    { ... video2  ...},
    { ... video3  ...},
    { ... video4  ...},
    { ... video5  ...},
    { ... video6  ...},
    { ... video7  ...},
    { ... video8  ...},
    { ... video9  ...},
    { ... video10 ...}
  ]
}

A válaszban szereplő totalhits érték elárulja az összes találat számát, a videos tömb tartalmazza egyoldalnyi (10 db) videó adatait. A tömbben szereplő videó-objektumok felépítése megfelel a getVideoData hívásnál ismertetettnek, az oembed_data tulajdonság kivételével, amely a keresés eredményeként visszakapott videó-objektumokban nem szerepel.

getCategoryVideos(name, sort, page)

A getCategoryVideos a megadott kategóriában lévő videók listáját adja vissza.

videa.getCategoryVideos("zene","upload_date",1).then(function(response) {
  // a lekérés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A hívás paraméterei:

name - a listázandó kategória neve. Az érvényes nevek: állatok, emberek/vlogok, felnőtt, film/animáció, hírek/politika, járművek, kreatív, nagyvilág, sport, tudomány/technika, vicces, zene.
sort - a találatok sorba rendezésének módja. Lehetséges értékek: title (videók címe szerint), upload_date (feltöltés ideje szerint), view_count (nézettség szerint).
page - a találatok hányadik oldalát kérjük, amennyiben egy oldalnyinál (10 db) több találat van.

A válasz formátuma:

{
  "cmd":"category_videos",
  "offset":0,
  "hits":10,
  "totalhits":33,
  "videos": [
    { ... video1  ...},
    { ... video2  ...},
    { ... video3  ...},
    { ... video4  ...},
    { ... video5  ...},
    { ... video6  ...},
    { ... video7  ...},
    { ... video8  ...},
    { ... video9  ...},
    { ... video10 ...}
  ]
}

A válasz formátuma megegyezik a searchVideos hívásnál ismertetettel.

getChannelVideos(name, sort, page)

A getChannelVideos a megadott csatornában lévő videók listáját adja vissza.

videa.getChannelVideos("Filmklub","upload_date",1).then(function(response) {
  // a lekérés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A hívás paraméterei:

name - a listázandó csatorna neve. Példa érvényes nevekre: Filmklub, Life, LifeTV, ORIGO, OzoneTV.
sort - a találatok sorba rendezésének módja. Lehetséges értékek: title (videók címe szerint), upload_date (feltöltés ideje szerint), view_count (nézettség szerint).
page - a találatok hányadik oldalát kérjük, amennyiben egy oldalnyinál (10 db) több találat van.

A válasz formátuma:

{
  "cmd":"channel_videos",
  "offset":0,
  "hits":10,
  "totalhits":33,
  "videos": [
    { ... video1  ...},
    { ... video2  ...},
    { ... video3  ...},
    { ... video4  ...},
    { ... video5  ...},
    { ... video6  ...},
    { ... video7  ...},
    { ... video8  ...},
    { ... video9  ...},
    { ... video10 ...}
  ]
}

A válasz formátuma megegyezik a searchVideos hívásnál ismertetettel.

getUserVideos(userId, sort, page)

A getUserVideos adott felhasználó által feltöltött videók listáját adja vissza a felhasználó numerikus azonosítója (userId) alapján.

videa.getUserVideos(1,"upload_date",1).then(function(response) {
  // a lekérés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A hívás paraméterei:

userId - a lekérdezendő felhasználó numerikus azonosítója. A felhasználó numerikus azonosítóját megkapjuk például az általa feltöltött videókra vonatkozó getVideoData hívásra kapott válaszban.
sort - a találatok sorba rendezésének módja. Lehetséges értékek: title (videók címe szerint), upload_date (feltöltés ideje szerint), view_count (nézettség szerint).
page - a találatok hányadik oldalát kérjük, amennyiben egy oldalnyinál (10 db) több találat van.

A válasz formátuma:

{
  "cmd":"user_videos",
  "offset":0,
  "hits":10,
  "totalhits":33,
  "videos": [
    { ... video1  ...},
    { ... video2  ...},
    { ... video3  ...},
    { ... video4  ...},
    { ... video5  ...},
    { ... video6  ...},
    { ... video7  ...},
    { ... video8  ...},
    { ... video9  ...},
    { ... video10 ...}
  ]
}

A válasz formátuma megegyezik a searchVideos hívásnál ismertetettel.

getTagVideos(name, sort, page)

A getTagVideos a megadott címkéhez tartozó videók listáját adja vissza.

videa.getTagVideos("kardhal","upload_date",1).then(function(response) {
  // a lekérés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
});

A hívás paraméterei:

name - a listázandó címke neve. Megadható bármilyen, az adott pillanatban a Videában létező címke.
sort - a találatok sorba rendezésének módja. Lehetséges értékek: title (videók címe szerint), upload_date (feltöltés ideje szerint), view_count (nézettség szerint).
page - a találatok hányadik oldalát kérjük, amennyiben egy oldalnyinál (10 db) több találat van.

A válasz formátuma:

{
  "cmd":"tag_videos",
  "offset":0,
  "hits":10,
  "totalhits":33,
  "videos": [
    { ... video1  ...},
    { ... video2  ...},
    { ... video3  ...},
    { ... video4  ...},
    { ... video5  ...},
    { ... video6  ...},
    { ... video7  ...},
    { ... video8  ...},
    { ... video9  ...},
    { ... video10 ...}
  ]
}

A válasz formátuma megegyezik a searchVideos hívásnál ismertetettel.

Hibakezelés

Ha egy kérés végrehajtása nem jár sikerrel, azt a JavaScript Promise objektumnak átadott hibakezelő függvényben tudjuk feldolgozni, amely egy error paraméterben kapja meg a hiba leírását:

videa.searchVideos("batman", 5).then(function(response) {
  // a keresés lefutott, a response változóban visszakaptuk az eredményt
}, function(error) {
  // valami hiba történt, az error változó tartalmazza ennek a jellemzőit
  alert(error.message);
});

A fenti példában szereplő error változó egy message tulajdonságban tartalmazza a hiba szöveges leírását. Amennyiben például hibás API kulcsot adunk meg, az error.message tulajdonság értéke appId invalid, ha pedig érvényes API kulcsunkat olyan webhelyen próbáljuk használni, amelyet korábban a kulcs beállításai között nem engedélyeztünk, origin error a visszakapott hibaüzenet. Hibát kaphatunk érvénytelen paraméterezés (pl. rosszul megadott kategórianév), hálózati hiba, átmeneti szerveroldali hiba miatt is.

Dokumentum verziók

2017. október 1.

Első publikus verzió

Beállításaim

PlayerAPI

Tetszőleges oldalba beágyazott Videa lejátszó vezérlésére és állapotának lekérdezésére szolgál.
A PlayerAPI segítségével létre tudunk hozni saját arculattal rendelkező videólejátszót, vagy az oldalunk működését tudjuk befolyásolni a videólejátszás állapotától függően.

Az API használatához szükség van egy egyedi API kulcsra, amelyet alább lehet igényelni.
Meg kell adni annak/azoknak a webhelyeknek a címét is, amelyeken az API működését engedélyezni szeretnénk. Csak az itt megadott oldalakon fog működni a PlayerAPI, más esetben hibás működést fog tapasztalni.

OpenAPI

A Videa OpenAPI segítségével saját weboldalunkban jeleníthetünk meg a Videáról származó tartalmakat: keresések eredményét, egy kategóriába, csatornába, feltöltő felhasználóhoz tartozó videók listáját, egy adott videó adatait.

Az API használatához szükség van egy egyedi API kulcsra, amelyet alább lehet igényelni.
Meg kell adni annak/azoknak a webhelyeknek a címét is, amelyeken az API működését engedélyezni szeretnénk. Csak az itt megadott oldalakon fog működni a OpenAPI, más esetben hibás működést fog tapasztalni.

Általános leírás fejlesztőknek

PlayerAPI

Bevezető

Előfeltételek

Példa

Videa PlayerAPI betöltése

Videa Player létrehozása

PlayerAPI használata beágyazó kóddal

Beágyazó kód megadása

API használatba vétele beágyazó kód esetén

Működés

Funkciók

playVideo

pauseVideo

isPlaying

seekTo(sec)

getCurrentTime

getDuration

getVersions

getSelectedVersion

changeVersion(name)

mute

unMute

getVolume

setVolume(n)

enableAutoplayNext

disableAutoplayNext

getFullscreenMode

requestFullscreen

cancelFullscreen

enablePlayerUI

disablePlayerUI

getVideoTitle

getVideoID

getVideoUrl

loadVideo(videoID)

loadAndStartVideo(videoID)

Eseménykezelők

onReady

onKeyError

Példa több lejátszó vezérlésére egy oldalon

Dokumentum verziók

2017. október 1.

OpenAPI

Bevezető

Előfeltételek

Példa

Videa OpenAPI betöltése

OpenAPI vezérlőobjektum létrehozása

OpenAPI vezérlőobjektum használata

Működés

Funkciók

getVideoData(videoId, maxWidth, maxHeight)

getProfileData(userId)

searchVideos(query, page)

getCategoryVideos(name, sort, page)

getChannelVideos(name, sort, page)

getUserVideos(userId, sort, page)

getTagVideos(name, sort, page)

Hibakezelés

Dokumentum verziók

2017. október 1.

PartnerAPI

Beállításaim

PlayerAPI

OpenAPI

Új webhely