Page Contents

    Getting Started with Interactivity

    In this topic you will learn how to connect your Brightcove account with HapYak.

    The HapYak plugin for the Brightcove Player allows the player to take advantage of the features provided by Brightcove Interactivity. Using the plugin has the following benefits:

    • Automatic Brightcove Interactivity project creation for each video viewed in the configured player
    • Programmatic access to video metadata from the HapYak Extension APIs
    • Dynamic loading of Brightcove Interactivity templates
    • Automatic syncing of project titles with video titles

    When interactions are added to a Brightcove Interactivity project, they will automatically appear on the corresponding video. This removes the need to copy and publish embed code within Brightcove Interactivity Studio.

    Configuring a Brightcove Player with the HapYak plugin

    Adding the HapYak plugin to a Brightcove Player will allow interactivity to be displayed inside of the player during video playback. The HapYak plugin can coexist with other player plugins. If you have questions on plugin compatibility, please contact Brightcove Support.

    To add the HapYak plugin to a Brightcove Player, follow these steps.

    1. Open the Players module.
    2. Click + Add player.
    3. Name the player HapYak Player and then click Save.
    4. Click the HapYak Player link to open the player properties.
    5. Click Plugins in the left navigation menu.
    6. Click Add a Plugin ˇ > Custom Plugin.
    7. For the Plugin Name use hapyak.
    8. For the JavaScript URL, use:
    9. If the player is also using the IMA3 plugin, the following should be added to the CSS URL:

      This will ensure the IMA3 plugin layer does not cover up any HapYak interactions.

    10. For the plugin Options(JSON), you will need the value of your HapYak API Read Key. To get your API Read Key, login to your Brightcove Interactivity account and click Integrations in the main navigation (or click here). When you have the key, for the Options(JSON) enter:
      "apiKey":"your HapYak API Read Key"
    11. Some mobile devices will strip interactive elements when videos are opened in device-native players such as the QuickTime player on iOS devices. HapYak has created a solution that overrides the default behavior of video on iOS and Android devices. By "mocking full screen", videos can play full screen and retain HapYak interactive features. The following parameters can be added to the Options(JSON) to improve the experience on mobile devices:
      • "loadFullScreenMobile" : true - Overrides the default fullscreen behavior on iOS devices
      • "position": "middle" - Ensures that the video appears in the middle of the devices display in portrait mode (mimics default behavior of all mobile devices)
    12. If you wish to configure a "read-only" player which will display interactivity on existing Brightcove Interactivity projects but will NOT publish any new projects, add the following parameter to the Options(JSON), below the apiKey value:
      “readOnly”: true
    13. Click Save.
    14. To publish the player, click Publish & Embed and then Publish Changes.

    The HapYak Player is now ready to use.

    Creating a Brightcove Interactivity project

    When a video is played inside of a HapYak-enabled Brightcove Player, the following things happen:

    • The Brightcove video ID, title, tags and custom fields are passed to Brightcove Interactivity.
    • Brightcove Interactivity attempts to look up the video ID within your group.
    • If no matching record is found, then Brightcove Interactivity creates a project with the data that was sent.
    • Brightcove Interactivity will also set the project properties to indicate that it was "auto created":
      • The is_published value will be set to TRUE
      • A tag with the value live will be added

    The following steps will automatically create a Brightcove Interactivity project:

    1. Open the Media module.
    2. Select a video to publish by checking the box next to the video thumbnail.
    3. Click Publish and embed... ˇ > Publish to web.
    4. Select the player with the HapYak plugin.
    5. Click the preview link to open a preview in a new browser tab.
    6. Play the preview video (the video only needs to be played for a few seconds). This will auto-create a project in Brightcove Interactivity.
    7. Login to Brightcove Interactivity Studio.
    8. In the left navigation, click Manage.
    9. A list of projects will appear. Confirm the video you just published appears in the project list.

    Adding a text overlay

    In this topic a simple text overlay will be added just to validate that the interactivity can be viewed inside of a Brightcove Player.

    1. In the Brightcove Interactivity UI, click on the project to open it.
    2. In the bottom toolbar, click on the text overlay button.
    3. Click on the Editor link in the menu.
    4. Enter some sample text for the overlay and click SUBMIT.
    5. Click Done.
    For detailed information on adding text and image overlays to videos, see Adding Interactive Overlays to Videos.

    Previewing and generating embed code for a video

    Once an interaction has been added to a Brightcove Interactivity project, preview the video to ensure the interactivity is working as expected. When a video is loaded in a HapYak-enabled Brightcove Player, the following things happen:

    1. The Brightcove video ID, title, tags and custom fields are sent to Brightcove Interactivity.
    2. Brightcove Interactivity attempts to look up the video ID within your Brightcove Interactivity group.
    3. If a matching record is found, then Brightcove Interactivity filters to the record that has the is_published value set to TRUE. The project with both the matching video ID and the is_published value set to TRUE will be displayed.
    4. If more than one matching record is found, then Brightcove Interactivity filters to the most recently modified record that has the is_published value set to TRUE. The most recently modified project with both the matching video ID and the is_published

    Follow these steps to preview and generate the embed code for the video:

    1. Open the Media module.
    2. Select the video you used to create the Brightcove Interactivity project and publish it.
    3. In the Select Player dropdown list, select the HapYak-enabled player.
    4. Click the URL below the preview player to open it in a new browser tab. Confirm that the interaction appears.
    5. Copy the embed code and paste it into your web page.

    Additionally, in the embed code, you MUST add playsinline inside the <video-js> tag. Please reference the examples below:


    style="position: relative; display: block; max-width: 960px;">
    style="padding-top: 56.25%;">
    style="position: absolute; top: 0px; right: 0px; bottom: 0px; left: 0px; width: 100%; height: 100%;"></iframe>


    <div style="max-width: 960px;">
    <video-js playsinline
    style="padding-top: 56.25%;">


    1. Annotations added to a project at the project level (meaning not through templates) should appear in approximately 90 seconds. Annotations added via templates can take up to two hours to appear.
    2. Do not manually create Brightcove projects in Brightcove Interactivity Studio. The plugin will do this automatically.
    3. Uploading a new video source files in Video Cloud will preserve the video ID and the connection to Brightcove Interactivity.
    4. Do not use the EMBED code generated from the Brightcove Interactivity tools when using the plugin. Instead publish your videos per the normal Brightcove workflow.
    5. Workflow-generated projects can be deleted using Brightcove Interactivity Studio. Please note that subsequent loads of the corresponding video through the Brightcove Player will not auto-generate a separate project in the portal.

    Page last updated on 21 Jul 2022