User Properties as External Data

You can use Personalized Stories for birthdays, personal offers by his or her name of a specific user, rewards and so on.
Instead of creating a whole personalized group with Storyly templates, you can try and create single personalized story, a personalized story group cover image or even personalized title on your groups.

👍

You can also check out the demo on GitHub

Storyly Demo for Kotlin

📘

Before you begin

You need to have the working Storyly setup as described in Initial SDK Setup

Add User Properties

To be able to have user properties on your story groups or stories, please go to Storyly Dashboard to add your properties.

🚧

Warning

Be sure to define unique property names in order to not to have problems while filling the user property fields in the application.

How to Use User Properties

Once you've added your user properties in the previous section, you can create a group from scratch. It is so simple to have personalized group cover image and title. Just select User Properties instead of Static and from the dropdown choose your related user property.

In studio, you can add texts and medias on your stories. If you select edit on a text and media, you'll be given two options Static & User Properties. To be able to create a personalized texts and medias, you have to select User Properties and choose whichever property you would like to use.

Setting User Property Data

You must set the data by using the following methods so that Storyly SDK can fill the user property fields and show the rendered stories to your users. You may set the data while initializing the Storyly SDK:

storylyView.storylyInit.userData = Map<String, String>

🚧

Warning

If you miss a field in an index of your user properties data, respective story group to that index will be ignored.

User Attributes as External Data

You can use Personalized Stories for birthdays, personal offers by his or her name of a specific user, rewards and so on.
This guide shows how to create templates and fill the templates from the Storyly SDK.

👍

You can also check out the demo on GitHub

Storyly Demo for Kotlin

Storyly Demo for Java

📘

Before you begin

You need to have the working Storyly setup as described in Initial SDK Setup

This guide shows creation of 2 different Stories with different templates.

Create Templates

In the Storyly Dashboard, while creating story groups, you will see an option called Create Personalized Stories. Here you can either select an existing template or create a new one in Template Studio.

🚧

Warning

Be sure to define unique field names for each story groups in order to not to have problems while filling the templates in the application.

Assume that your first template is a Birthday Story Template and consists of the following user-defined keys;

• image layer to show image of birthday with {media_2} field,
• text layer to show user names with {user_name} field,

Assume that your second template is an Abandonment Cart Template and consists of the following user-defined keys;

• image layer to show image of product with {media_1} field,
• text layer to show name of product with {product_name} field,
• text layer to show price of product with {price} field,
• text layer to show description of product with {description} field,
• button layer to handle user action with {cta_button} field,
• button layer to handle user action with {cta_url} field

📘

Tip

After saving your template, you can set a number in Maximum number of stories to specify how many stories will be displayed in Story Group. The number of stories varies depending on the data you send.

External Data Structure

According to the templates' needs, the application sets a custom data in a map format so that Storyly SDK can fill the fields in the templates above and show the rendered stories to the user. The following function/method is used to set the external data:

fun setExternalData(externalData: List<Map<String, Any?>>): Boolean {}

 @Override
public boolean setExternalData(List<Map<String, Object>> externalData) {}

You need to make sure that the templates' placeholders must match the structure in the external data attributes.

val externalData = mutableListOf<Map<String, Any?>>(
    mapOf(
        "{user_name}" to "user_name_url",
        "{media_2}" to "media_url_2",
        "{media_1}" to "media_url_1",
        "{product_name}" to "product_name_url"
        "{price}" to "price_url",
        "{description}" to "description_url"
        "{cta_button}" to "Buy Now",
        "{cta_url}" to "cta_url_info"
    ),
    mapOf(
        "{media_1}" to "media_url_1",
        "{product_name}" to "product_name_url"
        "{price}" to "price_url",
        "{description}" to "description_url"
        "{cta_button}" to "Buy Now",
        "{cta_url}" to "cta_url_info"
    )
)
storylyView.setExternalData(externalData)

List<Map<String, Object>> externalData = new ArrayList<>();
Map<String, Object> firstStoryOfStoryGroups = new HashMap<String, Object>() {{
    put("{media_2}", "media_url_2");
    put("{user_name}", "user_name_url");
    put("{media_1}", "media__url_1");
    put("{product_name}", "product_name_url");
    put("{price}", "price_url");
    put("{description}", "description_url");
    put("{cta_button}", "Buy Now");
    put("{cta_url}", "cta_url_info");
}};
Map<String, Object> secondStoryOfStoryGroups = new HashMap<String, Object>() {{
    put("{media_1}", "media__url_1");
    put("{product_name}", "product_name_url");
    put("{price}", "price_url");
    put("{description}", "description_url");
    put("{cta_button}", "Buy Now");
    put("{cta_url}", "cta_url_info");
}};
externalData.add(firstStoryOfStoryGroups);
externalData.add(secondStoryOfStoryGroups);
storylyView.setExternalData(externalData);

Each index of the external data represents the index of stories in each story groups.
For instance, first index of the list fills first stories of each story groups. Second index of the list fills second stories of each story groups and so on.

In our use case:

The field names of Birthday Story Template are listed in the first index thus Storyly SDK will fill the template and the Birthday Story will be displayed in the first story of the story group if {media_2} and {user_name} data are provided by external data.

The field names of Abandonment Cart Template are listed in both indexes thus Storyly SDK will fill the template and the Abandonment Cart Story will be displayed in the first and second stories of the story group if {media_1}, {product_name}, {price}, {description}, {cta_button}, and {cta_url} data are provided by external data.

🚧

Warning

If you miss a field in an index of your external data, respective story to that index will be ignored.

User IDs as Custom Parameter

In Storyly, you can use your audience to create automated personalized stories.

🚧

Warning

We do not recommend using Device ID as a user identifier. Frequent changes to Device ID may cause loss of personalized story data.

Add an Audience and Create Templates

First go to Audience under settings and add your CSV file.

You can give your Audience a name and after you can set the user identifier from your audience data. Once those are completed, click on `Create and your audience will be set.

Once you upload your CSV file, click on Create Personalized Stories and continue with Create Using Audience.

Choose which of the Audience data you'll be creating your automated personalized stories.

Select your desired template or create a new one in Template Studio.

Your data will be shown on this selected story template. Please match your data with the placeholders.

Passing Custom Parameter to Storyly SDK

This section shows you how to send a custom parameter for personalized stories.

Storyly SDK allows you to send a string parameter in the initialization process. In StorylyInit class, the customParameter field is used as user identifier for personalized stories.

class StorylyInit(storylyId: String, segmentation: StorylySegmentation, customParameter: String?)

class StorylyInit(String storylyId, StorylySegmentation segmentation, String customParameter)

🚧

Warning

You are allowed to send a 200 characters string value with the customParameter field. If you exceed the size limit, your value will be set to null.