Documentation

Rocketium Button is highly configurable. You can change its looks and behaviour, the editing experience, and also hook into various lifecycle events for complete control.

Configuration

The following options can be configured for Rocketium Button.

Key

Type

Value

entry-point

String

This controls what opens when the editor is opened by users. Allowed values are editor(default) and template-selection. editor opens the banner and video creator directly whereastemplate-selectionopens an intermediate screen that lets users browse and choose from already built templates.

button-mode

String

Allowed values simple and advanced. simple will open Campaign and advanced will open Studio

editor-type

String

Defines how the editor will open. There are two possible values for this inline and popup. Default is popup.

appendTo

String

ID of the div under which the creator should be added

clientId

String

Unique identifier for your account.

(contact Rocketium support)

workspaceId

String

ID of the workspace where you want videos to be saved.

templateId

String

ID of the template that should be opened by the editor. Once you export your template video, you can go to the Code tab within the Share settings of that video to get the template ID.

export-type

String

Allowed values are generate (default) and draft. generate renders the image or video when the export button is clicked. draft saves the image or video in the workspace so it can be rendered later.

layout (optional)

Boolean

Controls whether users can browse and choose individual layouts for every scene they add. Default value is true.

layout-panes (optional)

String

What layout panes to show, Applies if layout is set to true. Default value is both. Can be all-scenes, my-scenes or both.

layout-visibility (optional)

String

Whether to show private, public, or both in layout pane, Applies if layout is set to true. Default value is both. Can be public, private or both.

voice-over (optional)

Boolean

Controls whether users can add voice-overs from Rocketium's voice-over module.

media-library (optional)

Boolean

Controls whether users can access past images, videos, and music uploaded to your account. Default value is false.

show-Workspacelevel-Media (optional)

Boolean

If true, limits the assets shown while browsing the media library to whatever is in the workspace mentioned in the configuration. If not specified or false, all assets from every workspace of the owner account will be shown.

stock-library (optional)

Boolean

Controls whether users can search Rocketium's stock footage and image library. Default value is true.

media-upload (optional)

Boolean

Controls whether users can upload images and videos from their local machine. Default value is true.

preview (optional)

String

if button-mode is advanced.

Controls the features available to users in the preview. Can be either of off, basic or full. If off is chosen, users will not see a preview of the video. If basic is chosen, users will only be able to change video-level settings such as music and logo. If full is chosen, users will be able to choose from 30+ styling categories like fonts, colors, animations, and more. Default value is basic.

if button-mode is simple. off is not supported, basic will hide advanced edit, full will show advanced edit.

button-text (optional)

String

Text shown on the button

button-image (optional)

String

Image shown on button

button-color (optional)

String

Color of the button. Please provide a color hex-code

button-hidden (optional)

Boolean

Controls if the button should be hidden at launch. Default value is false. Set this to true if you want to trigger opening Rocketium editor programmatically.

editor-button-text (optional)

String

text shown on the editor button. Default will be Export.

export-and-close (optional)

Boolean

If true, closes the editor after export is clicked. If false, will keep the editor open after export is clicked. Default value is true.

export-on-error (optional)

Boolean

If true, closes the editor after export is clicked even if there is an error in the data. If false, will keep the editor open and show appropriate error message. Examples of errors are missing media, captions that are longer than allowed limits. Default value is true.

export-setting (optional)

Boolean

Controls whether export setting options to be shown or not. Default value is false.

fullHd (optional)

Boolean

Controls whether users see 1080p as an export option in export settings. Default value is false.

export-quality (optional)

String

Quality of the exported video. Can be full-hd, hd, or sd. Default value is hd. Note: Ensure export-setting is false when setting export-quality so users will not be able to select export quality inside the editor.

hide-export-button (optional)

String

Controls whether export video button to be shown or not. You would need to define your own button to call the GenerateVideo method. Default value is false.

video-name (optional)

String

Name of the video. This will be name for the video in the Rocketium dashboard.

metadata (optional)

Object

Custom information about the video that you can pass.

template-config (optional)

Template configuration object

Allows you to configure which templates will be shown in the template selection screen. This is only applicable if entry-point is template-selection.

custom-media-search (optional)

Media search configuration object

Enables Rocketium to fetch tagged media links from client servers and show them inside Rocketium's media library. A GET HTTP method API required to be shared by the client.

theme-css-url

(optional)

String

Enables changing the style of the white-label editor. You need to maintain a css file at your end with values for various CSS classes and provide the link to the file in this config.

Sample CSS file

campaignId

String

campaignId of what campaign to open.

features (optional) [DRAFT]

Feature configuration object

Specify the features that will be available in the editor

Media search configuration

Key

Type

Value

url

String

API URL endpoint to get media assets. Rocketium Button will make an HTTP GET request to your API. We support only REST APIs. This URL should not end in "/". (Required)

request-headers

String

Extra headers parameters that needs to be passed to API like Authorisation/authentication tokens. (optional)

user-id

String

Any custom tag to be queried, that the media assets are tagged with. workspaceId is used if no value is specified

filter-assets

String

Filter assets that you want in media library, It can be either both, stock or custom. Defaults to both.(optional)

pagination

Boolean

Set this flag to true if the API supports the pagination. Default value is false. page and limit will be sent as query param along with type to filter.

limit

Number

Sets the limit on the number of media assets fetched from API.

Example custom-media-config

"custom-media-search":{
"url": "<API to call>",
"request-headers":["<header1>", "<header2>"],
"filter-assets":"custom",
"limit" : 20,
"user-id":"<userId/workspaceId>",
"pagination": true
}

Expected Response Format

[
{
"thumbnailUrl": "<image_url>",
"downloadUrl": "<image_or_video_url>",
"type": "image"/"video"
},
{
"thumbnailUrl": "<image_url>",
"downloadUrl": "<image_or_video_url>",
"type": "image"/"video"
}...]

Template configuration

Key

Type

Value

tags (optional)

Array of String

If this is not specified, all templates are shown. If any tags are specified, only templates with those tags are shown.

orientations (optional)

Array of String

One or more orientations. Only templates in these orientations will be shown. Allowed values are landscape, portrait, square, facebook.

visibility (optional)

String

Allowed values are public, private, and both. Default value is both.

templateIds (optional)

Array of String

Send specific template IDs here if you want users to see only those templates.

Feature configuration

Key

Type

Value

line-spacing

Boolean

true enables the line spacing feature

letter-spacing

Boolean

true enables the line spacing feature

Events

Following events can be listened for using the sample code provided on the right.

Event name

Details

Attributes

rfsdk-editor-loading

Rocketium's editor is loading

None

rfsdk-editor-ready

Rocketium's editor is ready to be used by the user

videoId and videoShortId are returned in the data object of the callback.

rfsdk-video-exporting

User clicks on the Export button in Rocketium's editor. If there is an event handler for this event, the video will not be exported until the export method is called.

The attributes object will contain videoDuration that specifies the duration of the video.

rfsdk-video-exported

Rocketium's servers have received the request to render the video. The editor will auto-close at this point.

downloadUrl and other metadata related to the exported creative

rfsdk-export-without-close

Called upon video export if export-and-close is set to false in the init script.

downloadUrl and other metadata related to the exported creative

rfsdk-template-selection-loading

Rocketium's template selection screen is loading.

None

rfsdk-template-selection-ready

Rocketium's template selection screen is ready to be used.

None

rfsdk-receive-video-data

Will receive this callback after successful execution of the getvVideoData request by user. Callback receives a JSON object with video data.

None

rfsdk-receive-video-data-in-code-format

This callback will be received after successful execution of the getVideoDataInCodeFormat() request by the user. The JSON received would be directly compatible with createVideo API.

rfsdk-video-data-set

Received after successful execution of setVideoData request.

None

rfsdk-video-draft-saving

Called on starting save action in Rocketium's editor. Might be useful to show loader while saving video data.

None

rfsdk-video-draft-saved

Called on successfully saving video data.

None

rfsdk-editor-exit-clicked

Called on closing the Rocketium's editor.

None

rfsdk-campaign-editor-ready

Called when campaign editor is open

camapignId

rfsdk-campaign-ready

Called when campaign is ready to be used.

None

rfsdk-video-exported

Called when campaign gets exported

campaignId and metadata

rfsdk-campaign-advance-edit-open

Called when Advance edit is clicked.

None

rfsdk-campaign-advance-edit-close

Called when Advance edit is closed.

None

rfsdk-voice-over-set

Whenever user updates voice-over of a scene this event will be triggered.

None

rfsdk-voice-over-removed

This event is triggered when user removes voice-over from scene

None

rfsdk-save-draft-close

This event is triggered when the user clicked on export/save button and Button is configured with export-type: draft

videoId

Error Codes

Following are the error codes you might encounter while trying to setup Rocketium Form SDK on your webpage.

Error code

Details

Troubleshooting

RFSDK_MISSING_CONFIG

Required parameters are missing

Missing parameters will be emitted to the console. Update the script to add these entries.

RFSDK_INVALID_CONFIG

One or more parameters are invalid

Invalid parameters will be emitted to the console. Update the script to fix these entries.

RFSDK_OUT_OF_CREDITS

Your account does not have any more video credits.

Get in touch with your account manager or our support team.

RFSDK_INVALID_CLIENT_ID_OR_DOMAIN_NOT_WHITELISTED

The client ID is invalid or the domain on which Rocketium Button is running has not been whitelisted.

Check the client ID shared by the Rocketium team and ensure the current domain has been whitelisted.

RFSDK_INVALID_TEMPLATE_ID

The specified template ID is either invalid or unavailable for your account.

Correct the template ID sent while initialising.

RFSDK_INVALID_WORKSPACE_ID

The specified workspace ID is either invalid or unavailable for your account.

Correct the workspace ID sent while initialising.

Methods

Rocketium Button can be controlled with JavaScript. Various methods can be called to customize the behavior of the editor and define different entry-points and workflows associated to curate the user experience.

Method

Details

init

Initialise or change Rocketium Button configuration. This will not open Rocketium's editor. This is already a part of the sample script and does not need to be called again.

openEditor

This will open Rocketium's editor with the configured parameters. The editor opens automatically when a user clicks on the button. You need to call this method only if you want to hide the default button and open the editor based on user interaction on your site.

openVideo

When called this method will open Rocketium's editor with the given videoId. If you want to edit a video which is created previously, call this method and pass videoId as parameter.

showButton

This will show the Rocketium Button. You need to call this method only if you had previously hidden it.

hideButton

This will hide the Rocketium Button. You need to call this method only if you want to hide the default button and open the editor based on user interaction on your site.

loadTemplate

Once editor init method is called you can use loadTemplate to load any template accessible to you or a public template. loadTemplate accepts templateId as a parameter. Failing to provide a templateId will result in the creation of a blank video.

updateConfig

Instead of calling init again, you can use updateConfig to update configuration values at run time, changing config will be immediately reflected in editor.

openTemplateSelection

Accepts a Template Config object as a parameter.

save

This will save the current video.

generateVideo

This will generate the video. Required only if video export needs to be called externally. This would happen in two cases -

  • rfsdk-video-exporting event has an associated function, hence export will be paused until execution.

  • Export button in the editor is hidden in config and user has defined an external button for export.

getVideoData

Use this method to get the current video data. After calling this method you will receive data in rfsdk-receive-video-data callback.

getVideoDataInCodeFormat

Use this method to the get the current video data in JSON format compatible with the createVideo API. After calling this method, the data will be received in rfsdk-receive-video-data-in-code-format callback

setVideoData

Use this to programmatically manipulate video data. Video data should be compatible with Rocketium video format. On setting video data successfully rfsdk-video-data-set will be called.

openCampaign

Open Campaign with the given campaign ID.