Personalizing Widgets

There are two ways to personalize Story widgets using user-specific data:

1. Passing User Properties directly via the SDK using the userProperties object.
2. Using Custom Parameters with a CSV upload in the Storyly Dashboard to map user-specific values.

📘

Info

If you are already using Custom Parameters for audience targeting or segmentation, you can also upload a CSV file in the Storyly Dashboard and use the mapped values to populate user properties dynamically within your stories.

User Properties

User properties are used to fill placeholders in Studio (for example personalized titles, images, descriptions, call-to-action text/URLs).

Add and use user properties in Studio

1. Create user properties in the Storyly Dashboard.
2. In Storyly Studio, edit a text or media and choose User Properties.
3. Select the relevant user property. In Studio, placeholders are represented as @{property_name}.

🚧

Warning

Be sure to define unique property names to avoid mismatches between Studio placeholders and SDK data.

Pass user properties via SDK config

Use the userProperties object in init():

const config = {
  token: "<your_placement_token>",
  userProperties: {
    "{user_name}": "John",
    "{product_name}": "Running Shoes",
    "{price}": "$99.99",
    "{description}": "Limited time offer",
    "{cta_button}": "Buy Now",
  },
};

await storylyPlacement.init(config);

Update user properties after initialization

If you need to set or update user properties after you know the user’s data, call setUserPropertiesData(...) on the widget instance received in widgetReady:

storylyPlacement.on("widgetReady", async ({ widget }) => {
  if (typeof widget?.setUserPropertiesData !== "function") return;

  await widget.setUserPropertiesData({
    "{user_name}": "John",
    "{product_name}": "Running Shoes",
    "{price}": "$99.99",
    "{cta_button}": "Buy Now",
  });
});