IVS Player: Methods for accessing IVX API

The SDK provides access to IVX video and playlist data via an API, which can be used without building a player.

To access the API:

  <script src="https://player.ivideosmart.com/ivsplayer/v4/dist/js/loader.js"></script> <!-- no params needed -->
  <script>
      window.addEventListener('ivs.playersdk.loaded', function (event) {
         // Set credentials
         IVS.config.credentials.key = 'abc';

         // Create instance of API class
         let api = new IVS.Api();

         // Call method
         api.getPlaylists(function (response) {
           console.log(response);
         });
      })
  </script>

Each method in the API follows a similar method signature: function (callback, mandatoryArg1, optionalArg1). The callback is always first, followed by mandatory arguments and lastly optional arguments. The callback takes in an response object and returns void. Below is a sample of a response:

  {
      statusCode: 200,
      headers: {
          'Content-Type': 'application/json; charset=utf-8'
      },
      body: {
          data: null,
          error: null,
          meta: null
      }
  }

The methods in the API are as follows:

• getEntry(callback, videoId, productId): Get entry/video info. productId is optional.
• getWidget(callback, widgetId, videoId, productId): Get widget info. If videoId is specified, it will be prepended to the playlist in the widget and populate entry/video info. productId is optional.
• getCategories(callback, page, perPage): Get categories. page and perPage are optional.
• getCategory(callback, categoryId, videosPerPlaylist): Get a category. videosPerPlaylist is optional and refers to the number of videos for each playlist in the category.
• getPlaylists(callback, page, perPage): Get playlists. page and perPage are optional.
• getPlaylist(callback, playlistId, page, perPage): Get a playlist. page and perPage are optional and are used to paginate the entries in the playlist.
• findEntriesByTitle(callback, videoTitle, videoPlatform, videoPlatformId): Find entries/videos by video title. Note that page title may not always be exactly the same as the video title. One use case for this method is to find IVX videos corresponding to Youtube videos. E.g.: Service provider has a Youtube video with ID "ABC456" and title "Demo Video". To find the corresponding IVX videos (if any), call: findEntriesByTitle('Demo Video', 'youtube', 'ABC456'). Sample response (entries is [] if no videos):

  {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": {
      "entries": [
        {
          "id": 123,
          "name": "Demo Video",
          "thumbnail_url": "https://example.com/thumbnail.jpg",
          "platforms": {
            "youtube": {
              "id": "ABC456",
              "url": "https://www.youtube.com/embed/ABC456"
            },
            "ivideostream": {
              "id": 123
            },
            "livestream": null
          }
        }
      ]
    }
  }

• postPageInfo(callback, pageInfo): Post page info to iVideoSense recommendation engine used for generating content-based playlists. The use case for this method is when the player is unable to automatically scrape information from the webpage, e.g. it is embedded in an <iframe> and cannot access the parent page. This same method is called internally when an event of type ivs.page.data is sent to the player. pageInfo is a JSON object with the following structure (widget refers to the widget ID):

  {
    "widget": "abc",
    "curl": "https://example.com/canonical-url-of-page",
    "title": "Sample title",
    "textSummary": "Sample page summary",
    "text": "Sample article text.",
    "images": [
      "https://example.com/a.png",
      "https://example.com/b.jpg"
    ],
    "keywords": [
      "alpha, beta, gamma"
    ]
  }

Deprecated:

The old v2 IVX playlist API is deprecated: Technical Specification for IVX Playlist