Custom JavaScript Actions

The Creator Studio Custom JavaScript (JS) Action allows customers to specify code with run-time parameters to create custom functionality within an experience. For some examples of common custom actions, refer to this article.

Note: for the vast majority of cases, customers will never need to enter this area of the tool, as this is typically managed by our support and solutions teams. 

To get started with Custom JavaScript Actions, click "Set Up Integrations" in the Creator Studio menu at the top-right corner of the page:

Select the Custom JavaScript Actions tab to get an overview of the setup page:

Below we demonstrate how to set up a custom QuickView. 

Scenario:

Your website has product QuickViews which pop up a product window that allows the reader to add items to their cart or go to a product detail page. Let us assume the JavaScript code that triggers the QuickView Product Window is the following:

openProductWindow("P12A5");

In the above code, "openProductWindow" is the function name and "P12A5" is a product ID. Once executed, the code will open a QuickView window with all detailed information (images, price, quantity, etc...) for that product.

Prior the Custom JS Actions, it would be necessary to use the "Run JavaScript" action and copy/paste the entire code for each. This approach is fine for a few product links and when the QuickView function is short, but generally it is better to avoid copying and pasting excessively.

Solution:

Custom JS Actions help clients to reuse the same JavaScript code with just a single configuration. From the "Set Up Integrations" page, click the "Create New Action" button:

A lightbox will open. We'll use the sample code from earlier:

• Provide a name for the Action, for instance MyFirstCustomAction
• Paste the function into the text area, for instance openProductWindow("P12A5");

• Select or double click on the product ID P12A5. A green "plus" button will appear next to the selection.

• Click this button to add the selected characters as parameter to the function.

• Once the entry is visible in the Parameters list, you can rename it. This is how it will appear in the Editor later.

• Click 'Save' once finished.

IMPORTANT: You can only select parameters which are contained in quotes (" " or ' '). Acceptable parameter names include lower or upper case letters, numbers, and spaces. No special characters such as bullet points are accepted.

Once that your Custom JS Action is saved, it can be used in your Action Menu inside the Editor.

• Choose an experience where you want to use this action. Here we select a Text widget, for example.
• Add an action to it, and in the Action's "Type" menu you will see the newly created custom action, "MyFirstCustomAction".

• Once selected, you can specify the parameter value in the provided text-field. Notice the placeholder of the Action is called "Product Id", which is what we named it earlier.

• Now you only need to update one piece of information: the product id. In this case you insert the Product Id P536X.

• After saving, you are good to go and your custom JavaScript code openProductWindow("P536X"); will execute.

Is it possible to edit a Custom JS Action?

Custom JS Actions cannot be edited when used in an experience. The reason is that changes to a Custom Action will require a new push of the experience, which in most of cases is not ideal, since you may be editing a published Experience but not willing to push it live. For this reason, you will see a lock sign indicating which experience(s) the action is used. 

If you wish to edit a Custom JS Action used in experiences, you will need to first go through all experiences that contain the action and remove it, or delete the experience in question. Once the action has been removed from all experiences it can be edited again.

Are there any events tracked for a Custom JavaScript Action?

When a Custom Action is clicked the event history will be sent to Google Analytics (or a different provider if a custom integration has been built there).

The event name of the call is "Custom JavaScript Action Activated" and will also send over information such as name of the Custom JS Action followed by a dash-separated list of parameter objects containing parameter name and value.

Which characters can be used as a Custom JavaScript Action parameter in the Editor?

Permitted characters are letters (both uppercase and lowercase), numbers, and special characters as used in URLs (., :, /, \, _, ?, &, -, +, *, =,  #). Characters such as spaces and quotes must be avoided.