Import content in Tweakwise

If you want to transfer a large amount of product information between your platform and Tweakwise, you can use a specially formatted file to import that data. Tweakwise uses the XML format to perform this task. This is called the XML feed.

In this guide, we'll build a seperate content feed together:

  • Basic structure
  • Adding items
  • Adding attributes to items
  • Adding category links to items
  • Import the feed

You can view the full example feed at the bottom of the page.

Basic structure

Every XML document must have a root element. Our root element is 'tweakwise' and we'll open it with an opening tag <tweakwise>. Here's how that looks.

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <items>
    <!-- -->
  </items>
</tweakwise>

Adding items

Now we will add content inside the items element. For each content item an 'item' element should be added. An item has the following properties:

PropertyTypeMax lengthDescription
idalphanumeric100a unique identifier
namealphanumeric500the item name
imagealphanumeric500the main image URL
urlalphanumeric500a URL to the item page

Example

<item>
  <id>PROMO-shirts-june-2024</id>
  <name>Tweakwise T-Shirts</name>
  <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
  <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
</item>

Adding attributes

Introduce a specific attribute where you will store your item content type. This can be any attribute name, for example: item_type.

Contact us to configure the attribute as characteristic: the front-end API will use this type in the type field.

PropertyTypeMax lengthDescription
namealphanumeric100The attribute name.
Note: this field cannot not contain HTML.
valuealphanumeric400The attribute value.
<item>
  <id>PROMO-shirts-june-2024</id>
  <name>Tweakwise T-Shirt</name>
  <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
  <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
  <attributes>
    <attribute>
      <name>item_type</name>
      <value>visual</value>
    </attribute>
  </attributes>
</item>

Adding category links (optionally)

We have the option to link an item to an existing category. Doing so will automatically make these visual items visible on the category page. The order is determined based on the same specifications as the product items. If you only want to display visual items in the locations defined in our builder module, there’s no need to define any categories here.

<item>
  <id>PROMO-shirts-june-2024</id>
  <name>Tweakwise T-Shirt</name>
  ...
  <categories>
    <categoryid>promo-shirts-june</categoryid>
  </categories>
</item>

Full example

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <items>
    <item>
      <id>PROMO-shirts-june-2024</id>
      <name>Tweakwise T-Shirt</name>
      <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
      <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
      <attributes>
        <attribute>
          <name>item_type</name>
          <value>visual</value>
        </attribute>
      </attributes>
      <categories>
        <categoryid>Promo-shirts-june</categoryid>
      </categories>
    </item>
  </items>
</tweakwise> 

Good to know

  • If you don't have a basic understanding of XML, we recommend reading XML for the uninitiated.
  • This tutorial will guide you in generating a feed in any programming language or tool, as long as you know how to write text to a file using that language or tool. It will also help you manually create a feed if needed.
  • To increase readability, the examples contain different levels of indentation>> and newlines. This is not required in your feed. Removing tabs and newlines can make the feed size smaller and have impact on the performance of the import.
  • It is best practice to apply CDATA sections to all fields containing text. For example, image and url elements usually contain characters like an ampersand (&). To increase readability in this guide we omit this from some elements.