Before you start

Go to the Tweakwise app and gather the following information:

your instancekey (on the Tweakwise app dashboard)
your root category id (select the root category in the categories module, often 0)

To give the user a shopping experience they are used to, we advise to use a dedicated search results page. To make that work, create a specific page for that in Shopify.

Go to your store pages, and add a new dedicated page for the search results. Remember the page path. In this guide it will be/pages/results

Settings

Open config/settings_schema.liquid and add a Tweakwise section with settings for instancekey and the root categoryid:

{
    "name": "Tweakwise",
    "settings": [
      {
        "id": "tweakwise_instancekey",
        "type": "text",
        "label": "Tweakwise instancekey",
        "default": "your instancekey"
      },
      {
        "id": "tweakwise_root_cid",
        "type": "text",
        "label": "Tweakwise root category",
        "default": "0"
      }
    ]
  }

Notes:

The instancekey can be found in your Tweakwise App dashboard.
The cid must be the Tweakwise category id you want to scope your search to. You can find the category id in the Tweakwise app.

Installation

Create a snippet snippets/tweakwise-snippet.liquid and copy the following code:

{% comment %}
  Renders Tweakwise installation

  Accepts:
  - cid: {String} Tweakwise root category id

  Usage:
  {% render 'tweakwise-snippet' %}
{% endcomment %}

{% assign instancekey = settings.tweakwise_instancekey %}
{% assign cid = settings.tweakwise_root_cid %}

<link rel="preload" as="script" href="https://gateway.tweakwisenavigator.net/js/starter.js" />
<link rel="preload" as="script" href="https://gateway.tweakwisenavigator.net/js/{{ instancekey }}/tweakwise.js" />

<script defer="defer"
        src="https://gateway.tweakwisenavigator.net/js/{{ instancekey }}/tweakwise.js"
        data-failover="https://gateway.tweakwisenavigator.com/js/{{ instancekey }}/tweakwise.js"
        onerror="window.tweakwiseFailover(this.dataset.failover)"></script>

<script>(function(w, d, l, i, u) {w['_twa'] = l;w[l] = w[l] || [];w[l].push({ 'twa.start': new Date().getTime(), event: 'twa.js' });w[l].push({ 'twa.instance': i, event: 'twa.init' });var f = d.getElementsByTagName('script')[0],j = d.createElement('script');j.async = true;j.src = u;f.parentNode.insertBefore(j, f);
})(window, document, 'tweakwiseLayer', '{{ instancekey }}', "//navigator-analytics.tweakwise.com/bundles/scout.js");</script>

<!-- config overrides -->
<script>window["twn-starter-config"] = window["twn-starter-config"] || {};</script>
<script>
  window['twn-starter-config'].input = null;
  window['twn-starter-config'].cid = '{{ cid }}';
  window['twn-starter-config'].lang = '{{ request.locale.iso_code }}';
</script>

<script>
  window.addEventListener("twn.suggestions.ready", function () {
    window.tweakwiseSuggestions({
      input: "#tweakwise-input",
      instancekey: "{{ instancekey }}",
      cid: "{{ cid }}",
      lang: '{{ request.locale.iso_code }}',
      searchPhrases: {
        handle(event) {
          var suggestion = event.data;          
          location.href = '/page/results?tn_q=' + suggestion.match;
        }
      }
    });
  });
</script>

Apply the snippet in theme.liquid in the head:

{% render "tweakwise-snippet" %}

Notes:

The tweakwise-input selector can be remembered in a later stage

Search

To actually use the search results, we need an input as trigger for the search action.

Go to your header (depending on your theme) and add a dedicated search input on your desired location. If you already have a dedicated search input, alter the existing input:

Example: a simple input field

<div class="tweakwise-search">
  <form action="/pages/results">
		<input name="tn_q" id="tweakwise-input" autocomplete="off" placeholder="Search for something..">
  </form>
</div>

Notes:

If your theme already has a search input, make sure there's a form around it, so we can redirect to the search results page.
Make sure the form action is equal to the page path you created before (/pages/results).
Make sure the search query parameter is tn_q
If you already had a search input, update the input id to tweakwise-input so the suggestions get mapped correctly.

Lister pages

In order to display Tweakwise Merchandising on your collections, create a custom Tweakwise Product Grid section.
In the code editor, create a new section tweakwise-product-grid.liquid and copy the following snippet:

<div class="section-{{ section.id }}">
  <div id="tweakwise-navigation-output" class="page-width">
    <div class="tw-skeleton__container">
      <h3>Tweakwise Product Grid</h3>
      <div class="tw-skeleton__grid">
        <div class="tw-skeleton__left">
          <div class="tw-skeleton"> </div>
          <div class="tw-skeleton"> </div>
          <div class="tw-skeleton"> </div>
        </div>
        <div class="tw-skeleton__right">
          {% for i in (1..9) %}
          <div>
            <div class="tw-skeleton is-square"> </div>
            <div class="tw-skeleton is-low"> </div>
          </div>
          {% endfor %}
        </div>
      </div>
    </div>
  </div>
</div>

{%- style -%}
  .tw-skeleton__container { min-height: 100vh; }
  .tw-skeleton { background: #f2f2f2; margin-bottom: 20px; min-height: 1.5em; }
  .tw-skeleton.is-low { min-height: 1em; }
  .tw-skeleton.is-square { aspect-ratio: 1/1; margin-bottom: 7px; }
  .tw-skeleton.is-square + .tw-skeleton { margin-bottom: 10px; }
  .tw-skeleton__grid { display: grid; grid-template-columns: 1fr 3fr; gap: 20px; }
  .tw-skeleton__right { display: grid; grid-template-columns: 1fr 1fr 1fr; gap:10px; }
{%- endstyle -%}

<script>
window["twn-starter-config"] = window["twn-starter-config"] || {};
window['twn-starter-config'].navigation = {
  cid: '{{ collection.id }}',
  output: '#tweakwise-navigation-output' 
};
</script>
        
{% schema %}
  {
    "name": "Tweakwise Product Grid",
    "settings": [],
    "presets": [{
      "name": "Tweakwise Product Grid",
      "category": "Tweakwise"
    }]
  }
{% endschema %}

In the visual editor, a Tweakwise Product Grid section should be available. Replace the default Collection Product Grid with the Tweakwise Product Grid.

Recommendations

In the code ditor, create a new section tweakwise-recommendations.liquid and copy the following snippet:

<div class="section-{{ section.id }} section section--page-width">
  <div class="page-width tws-recommendations">
    
    <div class="tws-recommendations__title">
      <h3>{{ section.settings.title }}</h3>
    </div>
    
    <div class="tws-recommendations__body" id="tweakwise-recommendations" >      
      <div class="tw-skeleton__container">
        {% assign count =  8 %}
        {% if section.settings.view == 'carousel' %}
          {% assign count =  4 %}
        {% endif %}
        <div class="tw-skeleton__right is-{{section.settings.view}}">
          {% for i in (1..count) %}
          <div>
            <div class="tw-skeleton is-square"> </div>
            <div class="tw-skeleton is-low"> </div>
          </div>
          {% endfor %}
        </div>
      </div>
    </div>
  </div>
</div>

{%- style -%}
  .tws-recommendations__title {
    padding: 20px;
    text-align: center;
  }
  .tws-recommendations__body{margin: 0 0 40px 0;}
  .tw-skeleton { background: #f2f2f2; margin-bottom: 20px; min-height: 1.5em; }
  .tw-skeleton.is-low { min-height: 1em; }
  .tw-skeleton.is-square { aspect-ratio: 1/1; margin-bottom: 7px; }
  .tw-skeleton.is-square + .tw-skeleton { margin-bottom: 10px; }
  .tw-skeleton__right.is-carousel { display: grid; grid-template-columns: 1fr 1fr 1fr 1fr; gap:10px; }
  .tw-skeleton__right.is-grid { display: grid; grid-template-columns: 1fr 1fr 1fr 1fr; gap:10px; }
{%- endstyle -%}

{%  if section.settings.type != blank %}
<script>
  window.addEventListener("twn.recommendations.ready", function () {
    window.tweakwiseRecommendations({
      output: "#tweakwise-recommendations",
      instancekey: "{{settings.tweakwise_instancekey}}",
      view: "{{ section.settings.view }}",
{%  if section.settings.type == "related" %}
      related: {
        productId: "{{product.id}}",
        groupKey: "{{ section.settings.value }}"
      }
{% endif %}
{% if section.settings.type == "featured" %}
      featured: {
        id: "{{ section.settings.value }}"
      }
{%  endif %}
    });
  });
</script>
{%  endif %}

{% schema %}
  {
    "name": "Tweakwise Recommendations",
    "settings": [
      {
        "type": "text",
        "id": "title",
        "default": "For you",
        "label": "Title",
      },
      {
        "type": "select",
        "id": "type",
        "default": "featured",
        "options": [
          { "value": "featured", "label": "Featured" },
          { "value": "related", "label": "Related" }
        ],
        "label": "Type"
      },
      {
        "type": "text",
        "id": "value",
        "default": "cart",
        "label": "Group key/Featured id"
      },
      {
        "type": "select",
        "id": "view",
        "default": "carousel",
        "options": [
          { "value": "carousel", "label": "Carousel" },
          { "value": "grid", "label": "Grid" }
        ],
        "label": "View"
      }
    ],
    "presets": [{
      "name": "Tweakwise Recommendations",
      "category": "Tweakwise"
    }]
  }
{% endschema %}

In the visual editor, a Tweakwise Recommendations section should be available.

Replace the default Related Products or Featured Collection with the Tweakwise Recommendations and configure the correct type and group key or featured products id.

In the visual editor, new sections are available

Recommendations can be re-used in different templates

Notes:

The groupkey can be found in Tweakwise app in the up & cross selling recommendations module.
The featured products id can be foundin the Tweakwise app in the featured products recommendations module.