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.
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-selection opens 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 |
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. |
"custom-media-search":{
"url": "<API to call>",
"request-headers":["<header1>", "<header2>"],
"filter-assets":"custom",
"limit" : 20,
"user-id":"<userId/workspaceId>",
"pagination": true
}
[
{
"thumbnailUrl": "<image_url>",
"downloadUrl": "<image_or_video_url>",
"type": "image"/"video"
},
{
"thumbnailUrl": "<image_url>",
"downloadUrl": "<image_or_video_url>",
"type": "image"/"video"
}...]
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. |
Key | Type | Value |
line-spacing | Boolean | true enables the line spacing feature |
letter-spacing | Boolean | true enables the line spacing feature |
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 |
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. |
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 | |
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 - |
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. |