Stripo Plugin Reference

Getting Started

Hi! Welcome to the Plugin documentation. We are glad that you are interested in our service and we will be happy to help you out with all your questions.

The Stripo Plugin is written in native Javascript and designed as a component in a way to be easily configured and extended within any web application.

If you want to see how it works, the easiest way is to use our code samples from GitHub repository or follow the instructions from the video.

By using this simple client-side example, you can try out the Stripo Plugin:

• Get Plugin_ID and SECRET_KEY values by signing up here and creating a new application under the Plugin menu.
• Download the client-side code example.
• Open index.html with the code editor.
• Replace YOUR_Plugin_ID and YOUR_SECRET_KEY with your values.
• Save the file.
• Open it in your browser and enjoy email creation.

Please be advised that client-side examples are created just for demo purposes only and should NOT be used in production. It is insecure and your SECRET_KEY can be stolen. Keep your SECRET_KEY on your backend and do not share it with anyone. See the authentication process in detail to implement authentication correctly.

If you're ready to discover more, let’s move to the technical part that describes how to easily integrate the Stripo Plugin with your own web application.

Displaying the Plugin

The Plugin contains 2 parts: the setting panel and the preview area where your users work.

To install the Plugin you need to:

1. Define 2 containers for the Stripo settings panel (where controls will be located) and the Stripo preview area (the area where the rendered email template will be displayed).

   <div id="stripoSettingsContainer"></div>
   <div id="stripoPreviewContainer"></div>

2. Include the script taken from the application details page of the Stripo Plugin Integration menu of your Stripo account.

   To check the available versions of Stripo Plugin, please go to Release Notes.

   If you want to host Stripo Plugin assets on your end you can download them from Stripo Github repo: https://github.com/ardas/stripo-plugin.

3. Initialize the Plugin by using the window.Stripo.init function with its own JSON configuration described below.

Done! :) Once you have initialized the Stripo Plugin, you can pass a series of configuration parameters to it.

Initialization & Configuration

To initialize the Plugin you should create your own logic for your application. For example, you can display the templates on your interface and relate them with the initialization process so when a user clicks on one of them your application calls the initialization function and passes the HTML and CSS code of the selected template to it from your server. Or you can choose to simply add a button named “Create template” and upon a click on it, your application calls the same initialization function but passes the HTML and CSS code of the default empty template to it.

The general point is to start the initialization process and pass the list of needed parameters.

Once you have added the Stripo Plugin assets on your web page you need to initialize the Plugin:

window.Stripo.init({[put here your plugin JSON configuration]});

The default initialization script for Stripo Plugin should look like this:

window.Stripo.init({
   settingsId: '[put here ID of your settings container]',
   previewId: '[put here ID of your preview container]',
   html: '[put here HTML code of your email]',
   css: '[put here CSS code of your email]',
   apiRequestData: {
      emailId: '[put here ID of email in your external application]'
   },
   getAuthToken: function(callback) {
      //put here get Auth Token logic
   }
});

Let’s look at each parameter to understand why we need them.

Additionally, you can add other parameters to the initialization script. It allows you to get more opportunities for your users according to their category. For example, you can show them different social networks, modules, or merge tags.

As a result, you can independently determine all these parameters for each user (so they can be the same or different) every time during initialization.

Find the full list of them here:

If the editor is closed by the user in your web application, we recommend calling the following function to stop all processes and improve the performance of your application:

window.StripoApi.stop();

Please try out our example with the basic parameters to initialize the Plugin — https://github.com/ardas/stripo-Plugin-samples/tree/master/client-side-code-sample

Just create 2 text files on your device and rename them as in the example, then copy/paste all information from our files into the created ones, and don’t forget to add your own Plugin ID and Secret Key from the Stripo account in the index.html file.

Then you should double-click the Index.html file to get the initialization started.

Authentication Process

Authentication allows us to get an understanding of details concerning your account and the opportunities/limitations that you have. From the user's side, it allows them to have a real-time connection with our server and the understanding that everything works as it should.

The Stripo Plugin can't perform any operation without an authentication token. To authenticate your instance of the Stripo Plugin, call the endpoint shown in the sample code below with your Plugin Id and Secret Key, which are available on the Plugin details page. The Plugin calls the function each time a token is expired in order to get a new one.

So let's take a closer look at how Authentication works:

1. The Plugin configuration contains a parameter named getAuthToken. To get a new token the Plugin calls the getAuthToken function defined in Customer Application UI.
2. Customer Application UI sends the GET requests to the Customer Application Backend (for example, the "/token" request without any parameters).
3. Based on it the Customer Application Backend loads the "Plugin Id" and "Secret Key" values from the storage/database/file system.
4. After that, the Customer Application Backend sends the "/auth" POST request to the Stripo Plugin Backend with PluginId, secretKey, and role parameters.
5. As a response, the Stripo Backend generates the Plugin authentication token and
6. sends this token back to the Customer Application backend.
7. Finally, the Customer Application Backend sends a token back to the Customer Application UI, and there the Customer Application UI calls the callback(token) method from the getAuthToken method params to load this token to the Stripo Plugin.

To make it more clear please find the example of the getAuthToken implementation below:

getAuthToken: function(callback) {
   $.ajax({
  type: 'GET',
  url: '/backend/plugin/token',
  contentType: 'application/json; charset=utf-8',
  dataType: 'json',
  success: data => callback(data.token),
  error: error => callback(null)
   });
}

To get a token on your Backend, please call an endpoint from it, as shown in the sample code below, with your PluginId and Secret Key, which are available on the Plugin details page.

POST: /api/v1/auth
Host: https://plugins.stripo.email
Content-Type: application/json
Accept: application/json
Body: {pluginId:YOUR_PLUGIN_ID,secretKey:YOUR_SECRET_KEY,role:PLUGIN_EDITOR_USER_ROLE}
Response: {token:YOUR_AUTH_TOKEN}

AUTH REQUEST PARAMS:

Template requirements

The email templates that may be created/edited with Stripo editor, consist of two separate parts: the HTML code and the CSS code.

These parts of one template should be stored in your own database separately and passed simultaneously (see the initialization parameters) when the user decides to edit the template.

To check and compare the Stripo layout of the templates you can use our basic code from the repository.

In order to activate the editor's drag-n-drop feature for an imported email template, it is required the template has particular Stripo classes, which are used by the editor to parse the HTML layout correctly. In case you have a list of email templates created with another builder and you want to edit them with the Stripo editor, please make sure you have converted the HTML code of those templates correctly (with specific classes included in their HTML code) to activate Stripo editing features. Please, refer to this article from our blog with the list of all specific classes and examples of how to convert the HTML code — https://stripo.email/blog/advanced-option-email-templates-adaptation-stripo-builder/

To show the Stripo free email templates and display them in your application for your users for inspirational purposes, you can download them from here.

To provide your users with an option to create new email templates from scratch, please use the pre-built HTML and CSS code of an empty (scratch) email template which you can find here

It is required that the email template’s HTML code has at least one stripe with one structure in it.

How to Upgrade the Plugin?

We are glad that you decided to go further and upgrade your Plugin subscription plan! To do so, please open the Plugin tab in your Stripo account.

and choose Settings of a necessary application (if you have only one app, please choose it).

In the settings menu, you will get the opportunity to upgrade the subscription on a monthly basis.

If you want to get the invoice with the annual subscription, please email us at support@stripo.email.

UI Configuration

Interface Appearance in paid subscriptions only

In this section, you can configure the appearance of the Stripo Plugin to make it in the same style as your application.

How can you do that?

Just choose needed controls here and remove our Stripo branding.

Sometimes connecting the editor to applications that are also using Bootstrap CSS styles can cause a distorted look of the Plugin styles: components, alignment, etc.

This happens because the styles of your application affect the editor's styles. In this case, you need to isolate the influence of your application styles on our editor by connecting it to iframe or you should independently detect (using dev tools) which styles of your application affect the editor and change their scope (so that they do not work globally, but only for specific components).
If you have any questions on how to solve this problem, please feel free to contact our support team at support@stripo.email.

Image Storage

With the Stripo Plugin, you independently choose where all your images should be stored and it’s free for all pricing plans.

We are glad to provide our storage for your integration ー it’s actually specified as the default one in the settings.

Don’t want to store pictures on our end? No problem! Please choose any other preferable option and connect your own server to the image gallery.

Please, see the example of a configuration for Custom AWS S3 bucket, Azure Blob storage, or even your own server with the Other storage tab below.

Custom AWS S3 bucket

Custom AWS S3 bucket is a Plugin application configuration feature that allows you to easily connect your own Amazon Web Services S3 bucket to our Plugin for storing images.

If you choose this option, you’ll have to fill out a form to establish a connection with your storage. Please take a look at the image above to see the description of the form fields with specifications regarding the information required for each of them.

For more details on how to configure your AWS S3 storage please refer to this manual.

Azure Blob storage

Azure Blob storage is a Plugin application configuration feature that allows you to easily connect your own Azure storage account to our Plugin for storing images.

To do so, you need to generate a connection string in your Azure portal account:

If you choose the “Azure Blob Storage” option, you will have to fill out the form to establish a connection with your storage. Please take a look at the image above to see the description of the form field with specification regarding the information that you will need to enter there:

Other storage

This option may be the best choice for you if you’re using another storage type or want to build a more custom and flexible solution to host your images. We created a way to connect the Plugin to a custom file system provider (via HTTP protocol), allowing you to use the Stripo editor with your own file storage, no matter which technology you use.
It is required to support the set of the methods described below to provide successful communication between the two systems: the Stripo server and yours.

The Basic Authentication is used to send these requests, so please make sure that you have specified the correct Login, Password, and Base API URL on the Stripo Plugin details page of your Stripo account (if you don’t have an account, please sign up).

So, once the “Other storage” option is selected, make sure your server supports all the 4 types of requests with the exact specifications described below — GET LIST OF FILES, UPLOAD FILE TO STORAGE, DELETE/REMOVE FILE FROM STORAGE, GET FILE INFO.

GET LIST OF FILES

This method is used when the image gallery is opened inside the editor.

GET: /?keys=KEY_FOLDER_1,KEY_FOLDER_2,...
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Response: [{key: KEY_FOLDER_1, documents: [{url:DOC_URL,originalName:DOC_NAME,uploadTime:DOC_UPLOAD_TIME,size:DOC_SIZE_IN_BYTES,height:DOC_HEIGHT,width:DOC_WIDTH,thumbnailUrl:DOC_PREVIEW_URL}]}, {key: KEY_FOLDER_2, documents:[]}]

UPLOAD FILE TO STORAGE

This method is used when the user uploads an image to the image gallery.

POST: /
Host: YOUR_BASE_URL
Content-Type: multipart/form-data
Accept: application/json
Body: 
    key:KEY_FOLDER,
    file: MULTIPART_FILE
Response: {url:DOC_URL,originalName:DOC_NAME,uploadTime:DOC_UPLOAD_TIME,size:DOC_SIZE_IN_BYTES,
height:DOC_HEIGHT,width:DOC_WIDTH,thumbnailUrl:DOC_PREVIEW_URL}

DELETE/REMOVE FILE FROM STORAGE

This method is used to remove the system images only from the storage: like thumbnails of the modules, etc.

POST: /delete
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Body: {url:DOC_URL}

GET FILE INFO

This method is used for reading the specific information displayed on the Settings Panel about the selected image

GET: /info?src=DOC_URL
Host: YOUR_BASE_URL
Content-Type: application/json
Accept: application/json
Response:{"originalName":DOC_ORIGINAL_NAME,"size":DOC_SIZE_IN_BYTES}

Image Gallery. Folders configuration

You can see the image gallery at that time when you or your users choose an image for the “Image” block. You independently decide how many folders it contains and whether the user can only use it as drag-n-drop or also upload images to it for future usage.

For example, below you may see 3 folders in the image gallery named “Email”, “Project”, and “Common”.

These folders were created and configured on the Plugin details page this way:

In this section, you can manage:

• the number of folders;
• their names. You have the option to specify what names a created folder should have in every supported language;
• the path to images that should be stored in each folder;
• and also you can grant respective permissions.

You can specify the dynamic folder path to the repository and insert into it the variables that may be taken from your end when the Stripo editor is initialized.

For example, if you want to separate the images of one email template from another, you can create the "Emails" folder and specify its path as ${templateId}. When initializing the Plugin, you have to pass the templateId value (e.g., 00000) among the parameters in the apiRequestData and, as a result, the Plugin will get the images from the “00000” folder (this folder will be automatically created on a configured server if it does not exist yet).

If you have any questions on this matter, please contact our support team at support@stripo.email.

Limits

Below, you can specify the maximum size of one image uploaded to the gallery. The maximum value cannot exceed 20 Mb per one document.

Stock image configuration

If you want to provide your users with an option to search for and use free stock images within the image gallery while creating an email, you need to simply activate the "Stock images configuration" option.

Once it is activated, please specify the stock folder name, choose an available stock images provider, and specify the configuration according to the provided instructions.

The list of providers may be extended in the future.

Custom Gallery Connection

If you want to display your own UI component with an existing hierarchy of images and folders we have a great solution for you. The file with the example of the code describes how it may work.

When users want to use an image, instead of our gallery they will see an external gallery in the modal window. In that window, it’s up to you to define which images should be displayed and how, depending on a user that is currently working with the email in the editor.

To do so, you should initialize the Plugin with the parameter externalImagesLibrary and put your logic there. We expect that with the image that your user chose you will pass to the Plugin in callback parameters like original name, resolution, size and URL.

window.Stripo.init({
   ...,
   externalImagesLibrary: {
        openLibrary(onImageSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onImageSelectCallback({
                     originalName: 'YOUR_FILE_NAME.png',
                     resolution: '600 x 410 px',
                     size: '169.20 kb',
                     url: 'https://YOUR_STORAGE_URL/YOUR_FILE.png'
                  })
               when user select the image from external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }
});

You can also find the real example here and try it out on your side.

Modules Library

If you want to offer your users some interesting structures with a non-standard layout or provide the opportunity to save particular elements separately from the whole email (structures, containers, stripes) for future use and the easy drag-and-drop functionality you can fulfill it with modules.

Similar to the image gallery, a user may see as many folders (tabs) in the Modules tab as you've created and configured for your Plugin application.

In this section, you can manage:

• the number of folders;
• their names. You have the option to specify what names a created folder should have in every supported language;
• the storage key ID that will be assigned to modules and will be used as an identifier.
• and can even grant respective permissions.

You can specify the Storage Key ID as a static value or a variable (use braces, e.g. ${UserId}).

For example, if you want to restrict the access to one user’s modules from another user, you can create the ‘My modules’ folder and specify its path as ${UserId}. When initializing the Plugin, you have to pass the userId value (e.g., 00000) to apiRequestData parameter and, as a result, the Plugin will get the modules from the DB by the key “00000”.

Please be advised that you can turn off this feature so the Library section won’t display in the editor at all.

In this case, there won’t be an option to save selected elements from the context menu.

Merge Tags

You can personalize all emails based on your own variables connected to your platform. Merge tags (variables for personalization) help dynamically insert text templates into a text, like very common scripts (e.g., “Dear {first_name}” ). When you send the created email from your platform the variable from the tag will be changed automatically in accordance with the information from your database for a particular recipient.

Merge tags can be inserted from a text formatting panel of the ”Text” basic block by clicking on the “Merge tags” button in the expanded toolbar.

If you have activated this option while configuring the Plugin, the Stripo Plugin will handle all the transferred merge tags correctly, otherwise, this option won’t be displayed on the text formatting panel at all.

Here is the example of creation of mergeTags that you can pass with Plugin initialization:

{
    "mergeTags": [
        {
            "category": "MailChimp",
            "entries": [
                {
                    "label": "First Name",
                    "value": "*|FNAME|*"
                }
            ]
        }
    ]
}

Special Links

You can add more personalized links like Unsubscribe from sending or View in browser link in case if your customer wants to see email in web-browser. Special links option helps dynamically insert correct variables into an email. When you send the created email from your platform the variable from the tag will be changed automatically in accordance with the information from your database for a particular recipient.

Special link will be visible in a settings panel by clicking on the Link control.

If you have activated this option while configuring the Plugin, the Stripo Plugin will handle all the transferred special links correctly, otherwise, this option won’t be displayed in the settings panel at all.

Here is the example of creation of Special links that you can pass with Plugin initialization:

"specialLinks": [
{
    "category": "eSputnik",
    "entries": [
        {"label": "Unsubscribe", "value": "https://esputnik.com/unsubscribe"},
        {"label": "View in browser", "value": "https://esputnik.com/viewInBrowser"}
    ]
},
{
    "category": "Other",
    "entries": [
        {"label": "Some special link", "value": "https://some.special.link.url"}
    ]
}
]

Please find the descriptions of the parameters below:

Fonts management in paid subscriptions only

With this option, you can independently choose which fonts your users should see in the editor.

Font management helps you implement a variety of scenarios on your end. For example:

• you want your users to customize the list of fonts loaded in the editor when they edit emails. For this purpose, you can create an interface in your app, and configure the editor accordingly;
• you are a digital marketing agency and you want to customize the list of fonts in the editor according to a client’s brand for whom the email template is being created.

The list of fonts that should display in the editor must be defined each time the Plugin is initialized.
This helps you to:

• expand the list of available fonts displayed in the editor by adding own web fonts from popular services, like Google fonts and others;
• reduce the list of fonts to a limited number of options by removing the default fonts.

Please find the example of the code below:

{
    "editorFonts": {
        "showDefaultStandardFonts": true,
        "showDefaultNotStandardFonts": true,
        "customFonts": [
            {
                "name": "Oswald",
                "fontFamily": "'Oswald', 'helvetica neue', helvetica, arial, sans-serif",
                "url": "https://fonts.googleapis.com/css?family=Oswald"
            },
            {
                "name": "Barriecito",
                "fontFamily": "'Barriecito', cursive",
                "url": "https://fonts.googleapis.com/css?family=Barriecito&display=swap"
            }
        ]
    }
}

Please find the descriptions of parameters below:

Сustom Font Sizes list

You can display the font sizes in accordance with your brand identity and needs. It can be our standard or your own non-standard list with sizes.

The list of font sizes that should be displayed in the editor may be defined each time the Plugin is initialized. This helps you to achieve one of these scenarios:

• expanding the list of available font sizes displayed in the editor by adding own values of font sizes;
• reducing the list of font sizes to a limited number of options by removing the default sizes (standard and non-standard ones).

Here is the example of a font size object that you can pass with Plugin initialization:

"editorFontSizes": {
    "showDefaultStandardFontsSizes": false,
    "showDefaultNotStandardFontsSizes": true,
    "customFontsSizes": [17, 27, 32, 45]
}

In this case,

1. a default section (Non standard sizes) is loaded, and
2. 4 custom font sizes are added to the list (to the Custom sizes section).

Please find the descriptions of the parameters below:

Custom Color Palette

This feature helps you to decrease or increase the number of color options that appear on the color palette in the editor. These colors can be applied to text or other elements to make them more interesting and highlight important information.

The list of custom colors that should be displayed in the editor must be defined each time the Plugin is initialized. This approach helps you to implement a variety of scenarios on your end like:

• you want your users to customize a list of colors loaded in the editor when they edit emails;
• you can create an interface in your app to do so, and instruct the editor accordingly.

Here is an example of a custom color palette object that you can pass with Plugin initialization:

"customColorPalette": [
    "#882724",
    "#35882C",
    "#FFD351",
    "#1924FF",
    "#B621EC",
    "#95C4EC"
]

Please find the descriptions of the parameters below:

Display Conditions

Display conditions allow you to change the content of emails displayed to recipients, depending on whether the specified condition on your end is met or not.

Users can set conditions manually in the editor (Custom) or select them from a list of predefined conditions set earlier (Predefined).

Below you can see the Conditions tab with the custom condition category for the selected container.

Let’s have a look at the following use-case ー you’re preparing a sales newsletter for your eCommerce project. You’d like to show different banners for men and women in a single newsletter. In your user database, you are able to detect users’ gender.

So here how you can use this information to prepare customized newsletters. After the initial set up you’ll get the following result.

This is how women will see the email:

This is how men will see the email:

Now let’s go through the initial process of activating and customizing the Display Conditions for the editor users.

The very first thing to do is to activate the Display Conditions during Plugin initialization:

{
 ...
 conditionsEnabled: boolean = false; //activation of the Display Conditions tab in the Editor
 customConditionsEnabled: boolean = true; //ability to create Local Display Conditions inside the Editor
 conditionCategories: (PredefinedCategory | ExternalCategory)[] = []; //List of Condition categories
 ...
}

This activates the Conditions tab in the editor:

You may have some predefined categories that you want to apply to conditions and use them in the editor. In our example, this is Gender — Male & Female.

To pass the predefined conditions, please use the PredefinedCategory type which has the following configurations:

PredefinedCategory {
 type: string = 'PREDEFINED';
 category: string; //Category name
 conditions: PredefinedCondition[]; //conditions array with PredefinedCondition type
}

This is the configuration of predefined conditions:

PredefinedCondition {
 id: number; // unique ID of the Condition
 name: string;
 description: string;
 beforeScript: string;
 afterScript: string;
}

And this is the example of a predefined category with one condition:

{
 type: 'PREDEFINED',
 category:'Gender'
 conditions:[
  {
   id:1;
   name: 'Gender - female',
   description:'Only female customers will see this part of the email.',
   beforeScript:'{% if contact.gender === \"Female\" %}',
   afterScript:'{% endif %}';
  }
 ]
}

In the editor, we get the following:

The same could be set up for any condition, for example, Gender — male:

Instead of providing a list of predefined conditions, you can specify an External category which will allow you to implement your own condition selecting functionality. After the user selects the condition by the means you will provide to them, the latter will be sent back to the Plugin via a callback function.

Here is the type of external category:

ExternalCategory{
 type: string = 'EXTERNAL',
 category: string, //Category name
 openExternalDisplayConditionsDialog: (callback: ExternalDisplayConditionSelectedCB) => void; // callback that accepts a condition with type ExternalCondition
}

type ExternalDisplayConditionSelectedCB = (condition: ExternalCondition) => void;

ExternalCondition{
 name: string;
 description: string;
 beforeScript: string;
 afterScript: string;
}

Please see an example of an external category below:

{
 type: 'EXTERNAL',
 category:'Gaming platform'
 openExternalDisplayConditionsDialog: function(cb){
  // your code goes here
  cb({
   {
      name: 'Console',
      description:'Only console gamers will see this part of the email.',
      beforeScript:'{% if contact.gamingPlatform=== \"peasant\" %}',
      afterScript:'{% endif %}';
   }
  });
 }
}

Please see a full example of the Display Condition configuration:

{
 "conditionsEnabled": true,
 "customConditionsEnabled": true,
 "conditionCategories": [
   {
    "type": "PREDEFINED",
    "category":"Gender",
    "conditions":[
     {
      "id":1,
      "name": "Gender - female",
      "description":"Only female customers will see this part of the email.",
      "beforeScript":"{% if contact.gender === \"Female\" %}",
      "afterScript":"{% endif %}"
     }
    ]
   }
 ]
}

Undo-redo actions in paid subscriptions only

You can activate this feature to enable users to undo/redo their actions in the editor. Please be advised that you need to implement the undo/redo buttons by yourself outside the Stripo Plugin Editor, and pass their IDs during the Plugin initialization (see the “Plugin initialization and configuration” section). This allows you to place these buttons anywhere on your web page and design them the way you like.

Social Networks

If your users want to share any data about their organization or site to the social networks they could use our basic “Social Networks” block for these purposes. They can choose a lot of icons and different styles for them. If needed your users can even upload their own images to the “Social Networks” block and then apply a necessary link.

You can add your favorite social networks in the “Social Networks” block, too. Your users will see it this way:

This block also supports the Share links, so anyone can share the email to his/her social network.

To include your favorite (predefined) social networks, add a config parameter in the initialization script, as you can see in the example below:

{
    "socialNetworks": [
        {
            "name": "twitter",
            "href": ""
        },
        {
            "name": "facebook",
            "href": ""
        }
    ]
}

Please see the full list of supported network names or icons:

Ask.fm
Behance
Dribbble
Facebook
Flickr
Foursquare
Google-plus
Instagram
Last.fm
Linkedin
Livejournal
Myspace
Odnoklassniki
Pinterest
Soundcloud
Tumblr
Twitter
Vimeo
Vkontakte
Weibo
Youtube
Hangouts
ICQ
Mail.Ru Agent
Messenger
Skype
Snapchat
Telegram
Viber
Wechat
Whatsapp
Slack
Blogger
Email
Website
Map Marker
World
Address
Share
RSS
AppStore
Playmarket
Windows Store
Medium

Basic blocks management

The general menu with blocks can be configured and displayed for end users in accordance with your preferences and/or needs.

For example, if you don’t want to display AMP blocks because your service doesn't support them, you can just hide it in the Plugin for the end user.

In this case, once the Plugin is initialized users will see the blocks this way:

Advanced Controls in paid subscriptions only

In this section, we gathered some advanced controls that can help your users create their email templates in the most powerful way. The list of these controls with their explanations is as follows:

Image Rollover Effect

This feature is also known as a mouseover. When you place a mouse cursor over an image, the latter is replaced with another one.
The image rollover effect works on desktop devices only. Other users will see the primary image. It can be applied to any image you add in email except for the banner one.
How to implement an image rollover effect with Stripo:

1. Upload your first image.
2. In the settings panel, toggle the “Rollover effect” button.
3. Upload the second image — edit it if necessary.
4. Insert a URL link — it will be tied to both images.
5. Enter the “Alternate text”.
6. Set alignment and size of the images.

To learn more about how image rollover effect can be used read this article.

Mobile Padding

If you turn on this control when you configure the Plugin, it will be added to the set of controls for structures, stripes, and basic blocks (e.g. “Image’, “Text”, “Button”, etc.) in the Padding section and will appear like this:

When a user selects any structure or block in the editor and then decides to set up individual padding for mobile, all they need to do is activate this control and enter values — this structure or block will be displayed with the specified padding values on mobile devices.

Hiding an Element

If you turn on this control while you configure the Plugin, it will be added to the set of controls for every basic block (e.g. “Image”, “Text”, “Button”, etc.), containers, structures, and stripes and will appear like this:

When a user selects any of the elements in the editor and then decides not to display this element on mobile or on desktop only, all they need to do is activate this control and this is it — this element won’t be displayed when the email is opened on mobile devices or on desktop respectively.

Containers inversion on mobile

If you turn on this control when you configure the Plugin, it will be added to the set of structure controls only if there are 2 containers in it (the control will be hidden for structures with 1 or more than 2 containers inside) and will appear like this:

This control allows specifying which container should be displayed at the top and which one at the bottom of the mobile version of the email template.

If a user turns on the “Containers inversion on mobile” control, the containers will be placed on mobile the following way:

1. the first container on the desktop will be displayed as the second container on mobile;
2. the second container on the desktop will be displayed as the first one on mobile.

Alignment on Mobile

If you turn on this control when you configure the Plugin, the mobile icon will be added to the Alignment control of every basic block (e.g. “Image”, “Text”, “Button”, etc.) that have the “Alignment” control and will appear like this:

By default this icon is not activated, which means that the set alignment is relevant for the desktop version, yet will be the same for the mobile version if we do not specify another value.
To specify another value we should click on the “mobile” icon, it becomes activated (clicked), and then set another alignment by clicking on the proper icon here.

To switch back to the desktop version it is enough to click again on the “mobile” icon (it gets its default state when it’s non-clicked).

Border of Content of the Stripe

If you turn on this control when you configure the Plugin, it will be added to the set of stripe’s controls and will appear like this:

It allows setting the border for the content area of a selected stripe. It is possible to configure the borderline type (straight, dashed, dotted line), its color, and width for all sides or for a particular one (like only on the left side or on the top, etc.)

Background Color of Container

If you turn on this control when you configure the Plugin, it will be added to the set of container’s controls and will appear like this:

As the name suggests, this control allows setting up the background color for a selected container ;)

Background Image of Structure

If you turn on this control when you configure the Plugin, it will be added to the set of structure’s controls and will appear like this:

This control allows setting up any image as a background for a selected structure. It enables to configure the alignment and provides the ability to repeat a chosen image.

Background Image of Container

If you turn on this control when you configure the Plugin, it will be added to the set of container’s controls and will appear like this:

This control allows setting up any image as a background for a selected container. It enables to configure the alignment and provides the ability to repeat the chosen image.

Managing the Number of Containers in the Structure

If you turn on this control when you configure the Plugin, it will be added to the set of structure’s controls and will appear like this:

It allows adding or removing any existing container within a selected structure (it is possible to put up to 8 containers per structure). This control also allows changing the container’s width and indents between them.

Image Path

If you turn on this control when you configure the Plugin, the extra “Link” control will be added to the set of the Image block controls (as well as for the Menu, Banner blocks, etc) and will appear like this:

It allows specifying/replacing the URL to the image without making any changes to the HTML code. This feature is useful in case a user doesn’t want to place the image in your storage and simply wants to host it elsewhere (on an Internet site or any own storage of their own).

All they have to do is click on this “Link” control and replace the image URL with the required one in the “Image path” field.

Smart-elements Properties

This option provides the ability to activate smart properties for containers, structures, and stripes. If you activate this control when you configure the Plugin, and the user selects any container (structure or stripe) the new “Data” tab will be displayed at the top above the set of controls.

In this tab, a user has the ability to activate smart properties for a selected element and perform its configurations.

For more information about smart properties, please refer to our blog post – https://stripo.email/blog/smart-elements-reducing-time-creating-similar-letters-automating/.

Support of AMP HTML Mime type

In March 2019, Google released its AMP for emails technology. And as of July 2, 2019, it is available even for the G-Suite users and is “on” by default for all Gmail users. It allows senders to include AMP components inside engaging emails, making modern app functionality available within the email. This dynamic email format provides a subset of the AMP HTML components to use in email messages, that allows recipients of AMP emails to interact dynamically with content directly in the message.

Since June 18, 2019, Stripo has been supporting the creation of a new AMP HTML format of email template in the editor. To provide this option to your users you may activate the “Support of AMP HTML Mime type” on your Plugin details page. When it is activated and the user selects any block or container (structure or stripe) the new control will be added to the settings panel and will appear like this:

By default, all elements will be included in 2 versions of an email template: the traditional HTML version and the AMP HTML version. But users have a choice to include any element only in a particular version, for example, only in HTML or only in the AMP HTML version. In this case, that element will be highlighted with an orange border and a tooltip that indicates in which version that element is included. For more information on how to build AMP emails with Stripo, refer to our blog post – https://stripo.email/blog/how-to-build-amp-emails-with-stripo/

Image editor

This option helps you to enable or disable the image editor embedded in the Stripo Plugin. It helps to apply different effects to images, change their sizes, shapes, etc.
When it is activated and the user selects any image in email template, the new control will be added to the Settings panel and will appear like this:

Custom Components

External Images Library

If you have your own external image library that you would like your users to use while creating an email, you can display it instead of a Stripo image gallery. To do so, you need to set the externalImagesLibrary parameter when you initialize the Plugin:

To do so, you need to set the “externalImagesLibrary” parameter when you initialize the Plugin:

window.Stripo.init({
   ...,
   externalImagesLibrary: {
        openLibrary(onImageSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onImageSelectCallback({
                     originalName: 'YOUR_FILE_NAME.png',
                     resolution: '600 x 410 px',
                     size: '169.20 kb',
                     url: 'https://YOUR_STORAGE_URL/YOUR_FILE.png'
                  })
               when user select the image from external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }
});

Please find a code example here to see how it works.

External Video Library

Just like in the case with the external image library, you also may display your own component with an external library of videos.

To do so, you need to set the externalVideosLibrary parameter when you configure the Plugin:

window.Stripo.init({
  ...,
  externalVideosLibrary: {
      buttonText: 'YOUR BUTTON NAME',
      open: openLibrary(onVideoSelectCallback, onCancelCallback) {
          /* Put your logic here.
             Call
                onVideoSelectCallback({
                  originalVideoName: 'YOUR VIDEO NAME',
                  originalImageName: 'YOUR IMAGE NAME',
                  urlImage: 'https://YOUR_STORAGE_IMAGE_URL.png',
                  urlVideo: 'https://your_storage_url/YOUR_FILE',
                  hasCustomButton: true || false
                })
             when user select the video from external library.
             Call
                onCancelCallback()
             when user close the library without video selection.
          */
      }
  }
});

Please find a code example here to see how it works.

External Merge Tags

If you have your own merge tags library that you would like your users to use while creating an email, you can display it instead of a Stripo merge tags.

To do so, you need to set the externalMergeTags parameter when you initialize the Plugin:

window.Stripo.init({
...,
      externalMergeTags: {
      open: open(oneSelectCallback) {
         /* Put your logic here.
            Call
               oneSelectCallback('%%YPUR_MERGE_TAG%%')
               when user selects the merge tag from external.
         */
      }
  }
});

Please find a code example here to see how it works.

File Picker for Links

If you want to add your own control for selecting a file from an external file system in the pop-up window to be linked with the existing Link control for every basic block, you can set the externalFilesLibrary param when you initialize the Plugin:

window.Stripo.init({
  ...,
  externalFilesLibrary: {
        buttonText: 'YOUR BUTTON NAME',
        open: openLibrary(onFileSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onFileSelectCallback('https://YOUR_STORAGE_FILE_URL')
               when user select the file from external library.
               Call
                  onCancelCallback()
               when user close the library without file selection.
            */
        }
    }
});

As a result your customers can add the file by clicking on the right button.

Please find a code example here to see how it works.

Smart Modules

To display your own external data list in a pop-up window that users can choose to dynamically retrieve data from for their smart modules, you can set the externalSmartElementsLibrary parameter when you initialize the Plugin:

window.Stripo.init({
   ...,
   externalSmartElementsLibrary: {
        openLibrary(onDataSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onDataSelectCallback({
                	key: value
})
               when the user selects the data from the external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }
    }

Please find a code example here to see how it works.

If you want to provide option to choose whether use external data list or website data list, you can set up additional parameter enableWebSiteLinksForSmartElementsLibrary when you initialize the Plugin:

window.Stripo.init({
   ...,
   externalSmartElementsLibrary: {
        openLibrary(onDataSelectCallback, onCancelCallback) {
            /* Put your logic here.
               Call
                  onDataSelectCallback({
                	key: value
})
               when the user selects the data from the external library.
               Call
                  onCancelCallback()
               when user close the library without image selection.
            */
        }, enableWebSiteLinksForSmartElementsLibrary : true,
    }

As a result your customers can add their own data from the site or external source.

AMP Form Services

This parameter is an array of objects with the value and label fields that are used for collecting data from the AMP Form block. Label is the name of the service where the data from the AMP Form would be sent to, Value is a link to the endpoint for submitting forms.

  "ampFormServices": [
    {
      "label": "My endpoint 1",
      "value": "https://my-endpoint1.net"
    },
    {
      "label": "My endpoint 2",
      "value": "https://my-endpoint2.net"
    }
  ]

This is how a predefined list of services looks in the editor when a user clicks on the Form block inside their email template.

Editor extensions in business and enterprise subscriptions only

If you want to create your own editor blocks, flexibly customize their behavior and manage email layout, you can use the Stripo editor extensions.

First, create your own extension following the steps below:

1. Checkout out the https://github.com/ardas/stripo-plugin-samples repository
2. Navigate to preferred extension example in /extensions folder
3. Install dependencies:
   npm i
4. Replace sample extension code with your logic
5. Compile this code
   npm run build

The ready-to-use code will be stored in the dist folder. Then you will need to store the compiled extension files on your hosting. When you initialize the Plugin, insert the code sample given below:

  window.Stripo.init({
       ...,
       "extensions": [
           {
             "globalName": "YourExtensionName",
             "url":"https://your.hosting/main.hash.extension.js"
           }
         ]
   });

Please find the code example and detailed guidelines here.

Plugin Notifications

This is useful for those who want to show messages or notifications to users when an action is performed in the editor, e.g. the image is uploaded, the module is saved, etc.

You have the opportunity to display the editor’s messages with the script initialization and call one of these functions:

{
    "notifications": {
        "info": message => console.log(message),
        "error": message => console.error(message),
        "success": message => console.log(message),
        "warn": message => console.log(message),
        "loader": message => console.log(message),
        "hide": message => console.log(message)
    }
}

You need to configure these functions to show messages in the correct place and styled the way you like.

Server Configuration

In this chapter, you’ll find instructions on how to set up and customize the Plugin’s backend.

Permissions Checker API

Using this option you can be sure that only your users have the rights to edit emails in your application. Enable the permissions checker feature to prevent third-party people from pretending to be who they are not.

This means that the Stripo Plugin will not perform any server-side operation (load/save/update...) without permissions from your end. To enable this feature, you need to implement this backend endpoint on your server.

{
    "POST": "/",
    "Host": "YOUR_PERMISSIONS_CHECKER_URL",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Body": {
        "pluginId": "YOUR_PLUGIN_ID",
        "uiData": {
            "emailId": "123",
            "someAnotherIdentifier": "456",
            ...
        },
        "requestPermissions":
        [
            {
                "type": "BLOCKS",
                "action": "READ",
                "key": "pluginId_YOUR_PLUGIN_ID_emailId_123_id_456",
                "keyTemplate": "emailId_${emailId}_id_${someAnotherIdentifier}"
            },
            ...
        ]
    },
    "Response": {
        "grantPermissions": [
            {
                "type": "BLOCKS",
                "action": "READ",
                "key": "pluginId_YOUR_PLUGIN_ID_emailId_123_id_456",
                "keyTemplate": "emailId_${emailId}_id_${someAnotherIdentifier}"
            },
            ...
        ]
    }
}

Please take a look at the descriptions of the request parameters below:

Please take a look at the descriptions of the response parameters below:

When choosing the Permissions Checker API option, you have to fill out the form to establish a connection with your backend. This is a description of the form fields with specifications regarding what information you will need to provide:

AutoSave Option in paid subscriptions only

Whenever users make any changes to the email they are working on, these changes should be saved automatically. The Plugin sends micro changes (we call them “patches”) to its server, which in turn recreates the final version of the edited email template from them and sends it to your server for further saving/processing.

Enable the AutoSave option on the Plugin details page to receive a fresh version of the HTML and CSS code to your backend every time a change has been done by a user in the editor.

To support this option, you need to implement the interface on your backend that will receive the calls:

{
    "POST": "/",
    "Host": "YOUR_BACKEND_AUTO_SAVE_URL",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Body": {
        "key": "plId_YOUR_PLUGIN_ID_emailId_YOUR_EMAIL_ID_FROM_UI_REQUEST_PARAMS",
        "emailId": "YOUR_EMAIL_ID_FROM_UI_REQUEST_PARAMS",
        "html": "YOUR_HTML_CODE",
        "css": "YOUR_CSS_CODE",
        "width": "EMAIL_WIDTH",
        "height": "EMAIL_HEIGHT"
    },
    "Response status": "200 OK"
}

Please take a look at the descriptions of the request parameters below:

Version History in paid subscriptions only

This option enables your users to view changes of an opened email template in the editor, as well as gives the ability to restore any previous version of the email template from earlier versions.

When it is activated your users can track all changes displayed in the Settings Panel area. As soon as they click on a particular change, they are able to restore the opened email template to the selected version.

You can place the button/LINK (the trigger) in your application, by clicking on which the mode Version history of an opened email template will be activated.

Once this option is activated, please add these config parameters to the Plugin initialization call (see the “Plugin configuration” section):

{
    "userFullName": "YOUR_PLUGIN_USER_NAME",
    "versionHistory": {
        "changeHistoryLinkId": "YOUR_LINK_ELEMENT_ID",
        "onInitialized": "function(lastChangeInfoText)" {
            // Do any additional actions here when version history is initialized
        }
    }
}

If you do not use the AutoSave Option you can independently create the points displayed in the Version history section.

To do so, please add this function and call this method every time a template is saved on your end or when you want the corresponding entry to appear in the Version history:

function saveVersionHistoryPoint(onSaveCallback)
{
    if (window.StripoApi.createVersionHistoryPointAsync)
{
     	   window.StripoApi.createVersionHistoryPointAsync(onSaveCallback);
    }
   else {
        // Deprecated
        window.StripoApi.createVersionHistoryPoint();
        onSaveCallback();
    }
}

This function will create visible endpoints in the Version history and update the data of the last changes. You can independently choose where it should be applied, we recommend that you use it every time when your user clicks on the "Save" button.

Roles and Access Managements

Soon we will add the ability to manage the roles you can assign to any user when you initialize the editor.

Currently, there are only 2 roles preset by default in the system:

• Admin
• User

You can use these roles when you configure the access levels to the folders created in the image gallery and in the Library of modules. Pass correct roles with authentication (see the “Plugin authentication” section) to enable your users to write data in one or the other folder: the image gallery or the Library of modules.

Plugin Invocations

The Stripo Plugin has the Javascript API and Backend API, where the Javascript API is used for interaction with the UI part of the Plugin and the Backend API is used to combine two files, HTML and CSS, to get a ready-to-send email template.

Stripo Plugin JS API

The Stripo Plugin JS API can be accessed via the window.StripoApi js object.

The list of available JS API functions:

Stripo Plugin Backend API

As mentioned above, the Stripo Plugin Backend API endpoint allows inlining CSS styles into HTML tags and provides the final HTML code of email templates that is ready to be sent to recipients.

POST: /api/v1/cleaner/v1/compress
Host: https://plugins.stripo.email
Content-Type: application/json
Header: ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN
Accept: application/json
Body: {html:YOUR_HTML_CODE, css:YOUR_CSS_CODE, minimize:true}
Response: {html:HTML_READY_TO_BE_SENT}

Please see the descriptions of the request parameters below:

To get YOUR_AUTH_TOKEN please take a look at this section.

Example:

Request:
curl -X POST https://plugins.stripo.email/api/v1/auth -k -H "Content-Type: application/json" -H "Accept: application/json" --data "{\"pluginId\":\"YOUR_PLUGIN_ID\",\"secretKey\":\"YOUR_SECRET_KEY\"}" -i

Response:
{"token":"YOUR_AUTH_TOKEN"}

Request:
curl -X POST https://plugins.stripo.email/api/v1/cleaner/v1/compress -k -H "Content-Type: application/json" -H "Accept: application/json" -H "ES-PLUGIN-AUTH: Bearer YOUR_AUTH_TOKEN" --data "{\"html\":\"Some html\",\"css\":\"body {color: green}\",\"minimize\":true}" -i

Response:
{"html":"Some html"}

Helpers

How to Call the showAmpErrorsModal Function

Some errors may appear when users work on their emails. In order to notify your users about such errors and help them fix the bugs, the showAmpErrorsModal function is at your service.

Please see the example of how to call the showAmpErrorsModal function below:

showAmpErrorsModal(
	ampErrors,
	[
		{
			text: 'Preview',
			action: () => {console.log('"Preview" button clicked');}
		}
	],
	() => {console.log('"Close" button clicked');},
	() => {console.log('"Fix in Code Editor" button clicked');}
)

If you have set the option to display the code editor codeEditorButtonId, the “Fix in Code Editor” button will also be displayed:

Upon a click on this button, the preview window will be closed and the code editor will get opened instead. If you want anything else (not the code editor) to open upon a click on this button, then pass the 4th parameter to this function.

Once the “Close” button is clicked, you can add a callback function with the 3rd parameter, as well.
Upon a click on the red badge displayed on the code editor panel, the previous AMP errors will be displayed.

To run the email code validation again, the user has to click on the “Repeat check” button.

In case, no errors received once the email code validation check is completed, the editor will display the success notification message in the preview window as shown below:

If you want to display your custom buttons in this window, make sure you have passed them to the second parameter of the “showAmpErrorsModal” function. In our example above, we passed the “review” button that triggers opening the preview mode on an external application.

If the second parameter is empty, the only “Close” button will be displayed.

Configuration of AWS S3 Storage

To create custom AWS S3 storage, you need to:

1. Create an Amazon AWS account.
2. Create an IAM user with S3 bucket permissions.

3. Create IAM policy:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": "s3:ListBucket",
               "Resource": "arn:aws:s3:::bucketname"
           },
           {
               "Sid": "VisualEditor1",
               "Effect": "Allow",
               "Action": "s3:GetObject",
               "Resource": "arn:aws:s3:::bucketname/*"
           },
           {
               "Sid": "VisualEditor2",
               "Effect": "Allow",
               "Action": [
                   "s3:PutAnalyticsConfiguration",
                   "s3:GetObjectVersionTagging",
                   "s3:CreateBucket",
                   "s3:ReplicateObject",
                   "s3:GetObjectAcl",
                   "s3:DeleteBucketWebsite",
                   "s3:PutLifecycleConfiguration",
                   "s3:GetObjectVersionAcl",
                   "s3:DeleteObject",
                   "s3:GetBucketWebsite",
                   "s3:PutReplicationConfiguration",
                   "s3:GetBucketNotification",
                   "s3:PutBucketCORS",
                   "s3:GetReplicationConfiguration",
                   "s3:ListMultipartUploadParts",
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:PutBucketNotification",
                   "s3:PutBucketLogging",
                   "s3:GetAnalyticsConfiguration",
                   "s3:GetObjectVersionForReplication",
                   "s3:GetLifecycleConfiguration",
                   "s3:ListBucketByTags",
                   "s3:GetInventoryConfiguration",
                   "s3:GetBucketTagging",
                   "s3:PutAccelerateConfiguration",
                   "s3:DeleteObjectVersion",
                   "s3:GetBucketLogging",
                   "s3:ListBucketVersions",
                   "s3:RestoreObject",
                   "s3:ListBucket",
                   "s3:GetAccelerateConfiguration",
                   "s3:GetBucketPolicy",
                   "s3:GetObjectVersionTorrent",
                   "s3:AbortMultipartUpload",
                   "s3:GetBucketRequestPayment",
                   "s3:GetObjectTagging",
                   "s3:GetMetricsConfiguration",
                   "s3:DeleteBucket",
                   "s3:PutBucketVersioning",
                   "s3:ListBucketMultipartUploads",
                   "s3:PutMetricsConfiguration",
                   "s3:GetBucketVersioning",
                   "s3:GetBucketAcl",
                   "s3:PutInventoryConfiguration",
                   "s3:GetObjectTorrent",
                   "s3:PutBucketWebsite",
                   "s3:PutBucketRequestPayment",
                   "s3:GetBucketCORS",
                   "s3:GetBucketLocation",
                   "s3:ReplicateDelete",
                   "s3:GetObjectVersion"
               ],
               "Resource": "arn:aws:s3:::bucketname/*"
           },
           {
               "Sid": "VisualEditor3",
               "Effect": "Allow",
               "Action": [
                   "s3:ListAllMyBuckets",
               ],
               "Resource": "*"
           }
       ]
   }

   Please be advised that you should replace the bucketname value with the name of your bucket created in your AWS account.
4. Assign the created policy to the IAM user:
5. Create the S3 bucket with a necessary custom name and in a necessary region:
6. Choose Static website hosting and index document index.html:
7. Set Bucket permission policy.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "PublicReadGetObject",
               "Effect": "Allow",
               "Principal": "*",
               "Action": "s3:GetObject",
               "Resource": "arn:aws:s3:::bucketname/*"
           }
       ]
   }
   

   Please be advised that you should replace the bucketname value with the name of your bucket created in your AWS account.

8. Deactivate Objects from the bucket permissions:

9. Add settings to web server, e.g., nginx:

   location /content {
     add_header 'Access-Control-Allow-Origin' '*';
     proxy_pass  https://s3-eu-west-1.amazonaws.com/bucketname;
     proxy_redirect off;
   }
   

10. Enter “YOUR_DOMAIN_ADDRESS/content” as “Base Download URL” when you configure the Plugin settings.