Implementing Dancing Gifs Into Live Streams With The Giphy API

Published in

BingeWave

5 min readDec 27, 2021

In this tutorial we are going to cover how to make a Dancing Gif widget, where a random gif will be shown inside a live stream. We are going to cover the following technologies:

REST API + JSON
HTML
Javascript & Fetch
BWProperties
BWPlaceholders

Developing for BingeWave’s API makes creating interactive live streaming experiences. A developer can start by knowing basic HTML, CSS, Javascript, and JSON.

Getting Started And Github Repo

To get started, for developers that are new to building interactive widgets with BingeWave, please visit this short explainer on the Widget Builder and the process of building interactive solutions:

https://developers.bingewave.com/widgets/gettingstarted

All of our tutorials are accompanied by a Github Repo to assist developers in creating their widgets. To view the repository for this tutorial, please see here

https://github.com/BingeWave/widget-dancing-gif-example

HTML Of Widget

First, we are going to dive into this tutorial by implementing the HTML of the widget because it will only be three lines of code, which are as follows:

<div class="text-center">
  <div id="{{namespace}}_account_{{participant_id}}"></div>
</div>

The code above utilizes Dynamic BWPlaceholders, which are placeholders for values when they become available. The values that are replaced are the ones in the {{ }}.

The namespace placeholder will be replaced by the widgets namespace, a unique identifier for each widget. It is best practice to use the namespace to prevent collisions if another widget uses the same class or id.

The participant_id is the id of the current user who in the specified video. Because we want each user to have their own unique gif, we use the participant_id to identity each user.

In your widgets interface builder, copy and paste code as such:

Giphy API

Before we get to the Javascript, we need access to the Giphy API. Go to https://developers.giphy.com/ and register for a developer account. After you create the account, head over to the developer’s dashboard at https://developers.giphy.com/dashboard/. Create a new application, and you will be presented with the following options:

For now, select the API option, as this is all we will need to start. Afterward, you should have access to your create app API token as such:

Great! Now we head over to the search API at https://developers.giphy.com/docs/api/endpoint#search .Its fairly straightforward reading their documentation:

The search endpoint is https://api.giphy.com/v1/gifs/search, with the first parameter being the API Key you just created and the second parameter being the query of what you are searching for. When you call the API, it’s going to look something like this:

https://api.giphy.com/v1/gifs/search?api_key=xxxxx&q=transparent_dancing

That’s it! Now that we have this part done, it will make our Javascript really easy to implement.

Javascript

Next, we will implement our Javascript. We are going to separate the Javascript code into three different functions to create modular code. The first function will implement Giphy’s API:

We construct the URL using the API Key and the Query. The transparent-dancing query will return assets (pngs, webp, etc) that appear great over the video. Then we will utilize fetch for making a GET request to the URL.

Typically when fetch is used, the call is asynchronous, meaning the code will continue to execute without waiting for a response from the URL. The await makes fetch synchronous, and the code will wait for a response before continuing.

Finally, we parse the JSON response and return gifs. The API by default will return 25 gifs. We only want to show one gif on screen per user, so the next function will choose a single gif at random.

To break down this simple but a little bit complicated function:

Math.random : This function returns a number between 0 and .99 (less than 1). If there are 10 gifs and Math.random return 0.5, the index will be the fifth gif(10 *0.5 = 5). If Math.random returns a 0.9, it will return the 9th gif (10 * 0.9 = 9).

Math.floor: This function returns a whole number. So if Math.random multiplied by the length returns 9.9, Math.floor will make the number 9.

Because the gifs being passed in an array, the number return from the Math.floor will return a random index from the array. And finally, we need a function to place the gif on screen. See below.

In this function, we take a single gif and retrieve the webp image. The BWProperties is an object that every widget on BingeWave will have access to that contains important information about the current live stream. We want to reference the id of the HTML we defined in step 1:

<div class="text-center">
  <div id="{{namespace}}_account_{{participant_id}}"></div>
</div>

The BWProperties contains both the namespace and participant id. We can create the ID in Javascript that will match the above HTML id as such:

let id = BWProperties.namespace + "_account_" + BWProperties.participant.account.id;

And call the element like this:

let gif_container = document.getElementById(id);

And finally we create an image element, assign webp as the image source, and put it inside the div by its ID.

Calling The Functions

We currently have three separate functions that we need to tie together in their execution. We are simply going to create a load function to do just that, as send below.

The load function has to be made into an async function to review the above because we are using an await on the loadGifs function. Once all the gifs are returned, we select a single random one and place it on screen. And then, we call the load() function to run all three functions.

Your final Javascript should look like this:

Update your widget to make sure it saves. Afterwards head down to the test area and boot up the test video!