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.
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)
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)
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.
campaignId
String
campaignId of what campaign to open.
features (optional) [DRAFT]
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-project-exported
Rocketium's servers have received the request to render the project. The editor will redirect to the project view page that shows individual content variants and the rendered files.
metadata and campaignId of the project
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-project-editor-ready
Called when the project editor is ready.
campaignId
rfsdk-project-ready
Called when project is ready to be used.
None
rfsdk-video-exported
Called when campaign gets exported
campaignId and metadata
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.
openProject
Open the editor with the given project ID.