Customizing the player at runtime

When working with a Cincopa gallery or player, you usually customize its appearance and behavior using the Wizard UI. However, there may be situations where you need to make changes while the player is running — this is where the Runtime JavaScript API comes in handy.

Why Use the Runtime API?

The Runtime API allows you to adjust specific settings for a player instance during runtime. To do this, you need to:

1. Register for the runtime.on-args Event: This event triggers when the player is loading.

2. Modify the Args: After the event fires, you can change the specific player settings (called "args").

You can find a complete list of available args in the API documentation.

Common Use Cases

Here are some examples of what you can achieve using the Runtime API:

• Enable the Search Box: Allow users to search within the gallery.

• Disable Autoplay: Prevent videos from starting automatically.

• Override Embed and Share URLs: Customize how the player is shared.

• Change Player Color or Logo: Adjust branding in real-time.

• Add Dynamic Preroll and Postroll Ads: Manage advertisements effectively.

• Enable the Download Button: Allow users to download media.

Example: Enable Autostart and Play Button

Here's how you can enable autostart and display the play button using the Runtime API:

var cincopa = cincopa || {};
cincopa.registeredFunctions = cincopa.registeredFunctions || [];
cincopa.registeredFunctions.push({
	func: function (name, data, gallery) {
    gallery.args.autostart = "true";
    gallery.args.download_button = true;
  }, filter: "runtime.on-args"
});