App Integration

This app workflow is designed to integrate with the Creatopy editor. It allows users to start a session in the Creatopy editor (AdStudio or LightEditor) while logged in, directly from a link click.

To access this workflow, the integrating client must provide a JWT as an entry point. This token should contain the clientId, userId (for session impersonation), and an action defining what the session will do before redirecting the user to editor mode. All of this must be signed with the secret.

The clientId and secret pair are created in Creatopy under Team Settings/API credentials.

You can generate the token using the NodeJS script:

// nodejs
import jwt from 'jsonwebtoken';

const clientId = 'yourClientId'; // Replace with your actual clientId
const secret = 'yourSecret';     // Replace with your secret key

// Create the payload
const payload = {
  clientId,
  userId,
  action: {
    type: "create_blank_design",
    sizes: [{"width": 111, "height": 111}],
    projectId: 100,
    folderId: 111, // this is optional
    editorMode: "adstudio"
  }
};

// Sign the payload to create a JWT
const token = jwt.sign(payload, secret);

// Construct the URL
const url = `https://app.creatopy.com/token-auth/${token}`;

console.log(url);

or for testing purposes, you can use a JWT playground like the one from https://jwt.io/ where you can generate manually the token. To start the session just add the generated token to the Creatopy app https://app.creatopy.com/token-auth/${token}

JWT.IO example

The editor can be embedded in iframe too here's how: Iframe embedding

JWT Parameters

These are general parameters for starting the JWTtoken that starts the editor session.

Parameters for this action:

clientId - (required) The clientId form the API Configuration inside Creatopy app (the same that is used to generate bearer token to call APIs requests)

userId- (required) the userId for the user you impersonate in the session (if the clientId/secret pair is generated by the team owner or admin, you can impersonate users from your team).

action- (required) define the action that this session if started for defined here.

sessionConfig- usually UI configs for the current session. More on them here.

Actions for the session

To start a session, you need to provide an action type. Currently, we support four actions: create_design_from_template, create_blank_design, edit_design, and get_share_link. Add the action/type field in the JWT to call these actions. Each action has a set of specific parameters, which are explained for each type below.

"action": {
    "type": "create_design_from_template",
}

Edit design

This action will create a new design from an existing one (template).

Parameters for this action:

hash - The hash of the template (design or custom template)

editorMode - Which editor to open in the session ("adStudio" or "light-editor")

{
  "clientId": "YOUR-CLIENT_ID",
  "userId": userId,
  "action": {
    "type": "edit_design",
    "hash": "template-hash",
    "editorMode": "adstudio" | "light-editor"
  }
}

Create a design from a template

This action will create a new design from an already existing design (template).

Parameters for this action:

hash - The hash of the template (design or custom template)

name - The name I want the design to have (Optional)

projectId - ID of the project in which we want this design to be created

folderId - ID of the folder in which we want this design to be created (optional)

editorMode - Which editor to open in the session ("adStudio" or "light-editor")

{
  "clientId": "YOUR-CLIENT_ID",
  "userId": userId,
  "action": {
    "type": "create_design_from_template",
    "name": "My design name",
    "hash": "template-hash",
    "projectId": your-project-id,
    "folderId": your-folder-id, // this is optional
    "editorMode": "adstudio" | "light-editor"
  }
}

Create blank design

This action will create a new blank design.

Parameters for this action:

sizes - An array of sizes for the design

name - The name I want the design to have (Optional)

projectId - ID of the project where the design will be created

folderId - ID of the folder where the design will be created (optional)

editorMode - Editor to open in the session ("adStudio" only)

{
  "clientId": "YOUR-CLIENT_ID",
  "userId": userId,
  "action": {
    "type": "create_blank_design",
    "name": "My design",
    "sizes": [{"width": 111, "height": 111}],
    "projectId": your-project-id,
    "folderId": your-folder-id, // this is optional
    "editorMode": "adstudio"
  }
}

Get share link

This action will get you the shared link for a design or a folder based on the provided parameters, if you give a designHash, you will get a shared link for a design. And, if you give a folderId, you will get a shared link for a folder. One of these parameters must be provided. This action now supports an optional parameter, openRightBar, to provide additional functionality for the share link page.

Parameters for this action:

designHash - The hash of the design that you want its share link (could be undefined if you provide folderId)

folderId - The id of the folder that you want its share link (could be undefined if you provide designHash)

openRightBar- If true, opens the comments panel on the share link page. Has no effect if useShareLinkComments in the sessionConfig is disabled. (this param is optional and its default value is false)

{
  "clientId": "YOUR-CLIENT_ID",
  "userId": userId,
  "action": {
    "type": "get_share_link",
    "designHash": "design-hash", // mandatory for a design share link
    "folderId": 1234, // mandatory for a folder share link
    "openRightBar": true // the useShareLinkComments in the sessionConfig should be enabled to use this param
  }
}

Behavior of openRightBar Param

• When openRightBar is set to true:

  • The comments panel will open automatically when the share link page is accessed, provided that useShareLinkComments in the sessionConfig is enabled.

  • If useShareLinkComments is disabled, this parameter will be ignored, and the comments panel will not be displayed.

• When openRightBar is omitted or set to false, the comments panel will remain closed by default.

Flow: Create from Url (BETA)

This action will start the flow of creating a design from a URL using AI

Parameters for this action:

projectId - ID of the project where the design will be created

folderId - ID of the folder where the design will be created (optional)

{ 
	type: 'nextgen_flow_create_from_url', 
	projectId: 100,
	folderId: 124 // this param is optional
}

Flow: Create from a template (BETA)

This action will start the flow of creating a design from the template

Parameters for this action:

projectId - ID of the project where the design will be created

folderId - ID of the folder where the design will be created (optional)

{ 
	type: 'nextgen_flow_create_from_template', 
	projectId: 100,
	folderId: 124 // this param is optional
}

Flow: Create from assets (BETA)

This action will start the flow of creating design from assets (logo, images etc.)

Parameters for this action:

projectId - ID of the project where the design will be created

folderId - ID of the folder where the design will be created (optional)

{ 
	type: 'nextgen_flow_create_from_assets', 
	projectId: 100,
	folderId: 124 // this param is optional
}

Session Configuration

The sessionConfig object allows users to customize their white-label session by enabling or disabling certain features like design download and share link comments. By providing this configuration in their JWT token, end users can control session behavior based on their specific needs.

Object Structure

{
  "sessionConfig": {
    "useDownload": false,
    "useShareLinkComments": true,
    "useShareButton": true,
    "useAiEditText": false,
    "useAiEditImage": true,
    "useAiTranslate": false,
    "useAdServing": false,
    "brandkitIds": [1, 2, 3],
    "hideToolbarItems": ["templates", "elements"],
    "hideAllToolbarItemsExcept": null
  }
}

Properties

Property	Type	Default	Required	Description
useDownload	Boolean	false	No	Enables or disables the option to download design within the session. If true, download functionality is available; if false, it is disabled.
useShareLinkComments	Boolean	false	No	Enables or disables the option to add comments to share links within the session. If true, comments are allowed; if false, they are not.
useShareButton	Boolean	true	No	Enables or disables the option to use the share button. if true the share button appears, if false, the share button is hidden
useAiEditText	Boolean	true	No	Enables or disables the usage of editing text using AI. if true this option is enabled and if false it's disabled
useAiEditImage	Boolean	true	No	Enables or disables the usage of editing image using AI. if true this option is enabled and if false it's disabled
useAiTranslate	Boolean	true	No	Enables or disables the usage of translation using AI. if true this option is enabled and if false it's disabled
useAdServing	Boolean	true	No	Enables or disables the usage of Ad Serving. if true this option is enabled and if false it's disabled
brandkitIds	Array of Brandkit Ids	[]	No	Gives you the control to limit the brandkits that are shown in AdStudio. If it's not provided, the brandkits available will depand on the brand control defined on team and project level

Usage

To configure these session options, include the sessionConfig object in the payload of your JWT token. This configuration will then be applied to the session.

{
  "clientId": "YOUR-CLIENT_ID",
  "userId": userId,
  "action": {
    "type": "edit_design",
    "hash": "template-hash",
    "editorMode": "adstudio" | "genstudio"
  },
  "sessionConfig": {
    "useDownload": false,
    "useShareLinkComments": true,
    "useShareButton": true,
    "useAiEditText": false,
    "useAiEditImage": true,
    "useAiTranslate": false,
    "useAdServing": true,
    "brandkitIds": [123, 456]
  }
}

In this example:

• useDownload: false disables downloads for the session.

• useShareLinkComments: true enables comments on shared links.

• The share button is active (useShareButton: true).

• AI-powered text editing is disabled (useAiEditText: false), while AI image editing is enabled (useAiEditImage: true).

• AI translation is disabled (useAiTranslate: false).

• Ad serving is active (useAdServing: true).

• Brand-specific configurations are applied based on brandkitIds.

Notes

• Optional Properties: All properties in the sessionConfig object are optional. If not provided, default values will apply.

• You can start your session without the sessionConfig provided and the default values will also be applied in this case.

• Brand Kit Support: If brandkitIds is not specified or is an empty array, no brand-specific configurations will be applied.

Supported Toolbar Items (Tools)

The following toolbar items can be specified for hideToolbarItems or hideAllToolbarItemsExcept:

• "templates"

• "elements"

• "brandKit"

• "layers"

• "slides"

• "animator"

• "feedTool"

• "apps"

• "resize"

• "help"

Usage Rules for Toolbar Configuration

1. Mutual Exclusivity: The parameters hideToolbarItems and hideAllToolbarItemsExcept are mutually exclusive. You cannot use both at the same time. If both are provided, the session will fail to load the configuration.

2. Functionality:

   • hideToolbarItems: Specifies toolbar items to be removed from the left toolbar.

   • hideAllToolbarItemsExcept: Specifies toolbar items to remain visible, removing all others.

Examples

Example 1: Hiding Specific Toolbar Items

To hide only the "templates" and "elements" toolbar items:

jsonCopy code{
  "sessionConfig": {
    "hideToolbarItems": ["templates", "elements"]
  }
}

Example 2: Keeping Specific Toolbar Items Visible

To hide all toolbar items except "templates" and "elements":

jsonCopy code{
  "sessionConfig": {
    "hideAllToolbarItemsExcept": ["templates", "elements"]
  }
}

Notes

1. Empty Arrays: Providing an empty array for hideToolbarItems or hideAllToolbarItemsExcept will result in no changes to the toolbar.

2. Priority: Ensure only one of hideToolbarItems or hideAllToolbarItemsExcept is included to avoid conflicts.

3. User Experience: Consider the user's workflow before hiding or limiting access to toolbar items to ensure functionality aligns with their needs.