Storyblok x Tweakwise

Visual Components brings product content and inspiration together in dynamic lister pages. Show visuals exactly where visitors look and increase engagement and conversion. You manage everything yourself in the Builder, giving you the freedom to test, optimize and tweak anytime. Faster, more relevant and fully aligned with your brand.

We cover two approaches to accomplish this:

1. The Flexible Approach (Recommended): Storing only the Storyblok ID in Tweakwise and fetching content dynamically on the frontend.
2. The Simpler Approach: Storing the actual Storyblok content directly in Tweakwise attributes.

Implementation Guide

1. Introduce a new Item Type

First, you need to differentiate your visual content from standard products. You can accomplish this in two ways:

• Create items manually within the Tweakwise app.
• Create a separate Storyblok import using an XML feed. Follow the documentation on creating an XML feed to import content. Make sure these items have their item-type set to storyblok.

2. Add Storyblok Attributes to the Item

Depending on the approach you choose, populate your feed with the necessary data.

Option A: The Flexible Approach (recommended) Instead of pushing all content to Tweakwise, you only pass the reference.

• Add the storyblok_id to the item as an attribute.

Option B: The Simpler Approach If you want to avoid a secondary API call on the frontend, push the content directly.

• Add the Storyblok content (e.g., storyblok_title, storyblok_button_text, storyblok_image_url) to the item as attributes.

3. Expose Attributes Through the API

Ensure the newly created attributes are checked to be exposed in the Tweakwise API.

• Go to the attribute list configuration in Tweakwise and search for the respective attributes (e.g., storyblok_id) and follow the guide: Extend API response.

4. Render on the Frontend

When your frontend requests a lister page, Tweakwise returns a mix of standard products and your new storyblok items.

If using Option A:

1. Identify items in the response where the type is storyblok.
2. Extract the storyblok_id attribute.
3. Use this ID to execute a fetch request to the Storyblok API.
4. Render the rich visual component using the returned Storyblok details.

If using Option B:

1. Identify items where the type is storyblok.
2. Extract the content attributes (title, button, etc.) directly from the Tweakwise API response.
3. Render your visual component immediately using these values.

Important Considerations

• Frontend Performance: If you use the flexible approach (fetching by ID), your frontend must make additional HTTP requests to Storyblok. Implement a caching layer or use SSR/SSG to prevent layout shifts and optimize load times.
• Merchandising: You can use Tweakwise's merchandising rules to pin these storyblok items to specific positions in the grid (e.g., position 4 on the "Sale" category).
• Feed Updates: If using the simpler approach (storing content in Tweakwise), remember that any text or image change in Storyblok requires a new feed import into Tweakwise before it goes live.

FAQ

Q: Why should I use the ID-based approach instead of pushing all content to Tweakwise? A: Passing only the storyblok_id keeps your Tweakwise feed lightweight and decouples your content management from your product feed. If marketing updates a banner image in Storyblok, the change is instant on the frontend without waiting for a Tweakwise feed import.

Q: How do I control where the Storyblok visual appears in the lister page grid? A: Treat the Storyblok item just like a product. Use the Tweakwise Builder to select a specific spot on the lister page.

Q: My frontend isn't receiving the storyblok_id attribute. What's wrong? A: Double-check your property settings in the Tweakwise app. The attribute must be explicitly set to be exposed in the API response: Extend API response with an attribute.