Algolia Integration (Early Access)

Algolia is a powerful search-as-a-service solution powering search for the world’s top brands in a variety of verticals. The Integration with Algolia, leverages Dynamic Yield’s insightful user engagement attributes and Machine Learning (ML) powered insights adding a layer of personalization to Algolia.

Key benefits

1. Minimizing on-boarding effort by taking care of the product feed indexing in both platforms
2. Dynamic Yield product popularity scoring is incorporated into Algolia’s Index enhancing search results pages
3. Personalization is enabled by factoring Dynamic Yield’s User Affinity to search results. [requires User affinity API integration]
4. Testing and optimizing can be leveraged by using Dynamic Yield’s Audiences

Use Cases

1. Personalize search results to provide the “best match” for each and every visitor (affinity-based).
2. Target Audience. For example, sort search results by price (high to low) for your price-insensitive audience. 
3. Create merchandizing ‘boosting’ rules using Dynamic Yield’s audiences - for example, boost Adidas brand for “Adidas lovers” affinity audience. Another example, show ‘Ted Baker’ products for men searching ‘bags’ but show ‘Steve Madden’ product for women for the same query.

Prerequisites 

1. A Dynamic Yield and an Algolia Account. Each account is sold and managed separately. 
2. A Dynamic Yield product feed. Multi-language feeds are not supported.
3. Your product feed must be synced incrementally using Dynamic Yield’s Delta feed-sync API. If the Algolia integration is already in place, it is possible to use the client-side integration (affinity injection only) and not use the feed integration. In that case, you do not need to enable the integration in the integration screen.

How It Works 

When you integrate Algolia via Dynamic Yield, Dynamic Yield passes your product feed and product scores automatically to Algolia. The feed is made available in Algolia as an Index and allows you to return results based on product popularity score. 

To personalize results, Dynamic Yield’s User Affinity Profile is passed over to Algolia in real-time. When a visitor lands on a category page, or when the search results are returned, Algolia sorts the results based on the individual’s user affinity. Namely, it activates Algolia’s optional filters to order results boosting the affinity attributes of each user.

Advanced - you can selectively enable any merchandising rule - Rule Context (created in Algolia). Consequently, you can target Audiences created in Dynamic Yield, with specific rules. 

Setting Up the Integration

There are 3 elements to the integration setup depending on your use case (not all mandatory):

1. Integration Enablement - Matching between your Dynamic Yield and Algolia account
1. Setting up indexes, ranking, and context rules.
2. Popularity score - Setting up the ranking formula to leverage Dynamic Yield’s popularity scores.
2. Affinity Injection - Injection the Affinity profile for a specific user in real-time through Algolia’s optional filters. When you call Algolia’s API, these filters promote results based on the affinity profile of a user.
3. Activation - Creating respective experiences in Dynamic Yield that activate your Algolia Index along any merchandising rules to leverage targeting, optimization, and personalization. 

Integration Enablement 

1. The feed integration is activated via the Dynamic Yield platform. Contact your Dynamic Yield Customer Success Manager to enable access. There is no need to enable the integration in the Dynamic Yield platform for the affinity injection or the optimization.
2. Make sure you have a synced product feed and updated via API.
3. Once access is provided, in the Dynamic Yield’s console, go to Settings › Integrations and select Algolia.
4. Enable the integration and enter your Algolia application ID and Admin key. You can find your Algolia ID and admin key under API Keys within your Algolia console. 
   

Feed Set Up

1. Once the integration is activated in the Dynamic Yield console, Dynamic Yield begins syncing your feed (with your Dynamic Yield’s section name) to your Algolia account as an Index. The integration is on a specific site, so it should be enabled for each site separately under the account.
2. The mandatory attributes required by Dynamic Yield are sufficient to drive Algolia’s engine. The ‘Description’ product attribute, which is optional for Dynamic Yield, is important to add as an additional attribute and is relevant for a Search engine. 
3. When your feed is updated in Dynamic Yield, it is automatically updated (in real time) in your Algolia account.
4. Additional aspects of the integration include (informative) - 
   1. hierarchialCategories: { lvl0: “Shoes”, lvl1:”Shoes>Sneakers”}
1. Category hierarchy is parsed and transferred as a hierarchical object for faceting purposes. For example, if your feed includes a product with category (Shoes|Sneakers), your Algolia’s index will also include the following object - 
2. To take into consideration the relationship between the SKU and the group_id in Dynamic Yield, we defined group_id as a distinctable attribute on indexing time. This unlocks your capability to use the distinct feature in Algolia that enables de-duplication or grouping of results. 

Popularity Scores

1. Dynamic Yield’s popularity scores are automatically reported to Algolia as an additional attribute called “product_score” within each index.
2. Popularity scores are pushed twice daily, asynchronously to the metadata of your feed and will be found in your feed attribute. You can then choose to add it to your ranking formula under a new custom ranking called ‘product_score’. Read more about managing the ranking formula of your indexes here. 

Activation

1. There are multiple ways to leverage Dynamic Yield and Algolia together as described above. A best practice is to use a custom action to push all the relevant information to the page when needed and per the use-case.
2. Add experience/s to test different design options, target different visitor segments, or test different ranking formulas (Indexes). For example, you can set an experience targeting ‘budget shoppers’ and set the default result to be ordered by (ascending) price.
3. Create a template. We recommend adding a variable to the template allowing you to enable/disable the affinity injection or modify context rules easily for example. This way, you can test and target different experiences with additional ranking formulas and rules. Learn how to create a custom template. For details, see Injecting Affinity below. 
4. Connect the Variation to your Algolia Index of choice. Use the template variables to indicate which index the variation should trigger. Using the previous example, you can select the ‘sort by ascending price’ index for your ‘low budget shopper’ audience. Learn more about setting your indexes in Algolia. See the code examples below to place in your template.
5. Connect the variation to your Algolia ‘Rule Context’. To serve different merchandising rules for different audiences, you must indicate which rule should be activated. For example, for your ‘budget shoppers’ add a rule to only show items under $50. 
1. Learn more about setting up Rule context in Algolia. 
2. See the code examples below to learn how to place in your Dynamic Yield template for activation.

Injecting Affinity

1. Create a Custom Action and target all pages that are serving Algolia.
2. Add variation and paste the code described below.
3. Save the Custom Action.

The Custom Action will expose an object called ‘DY.CS.affinityToAlgolia’ that contains the Affinity DY according to Algolia format for injecting optional filters. When you initialize Algolia API - 

1. Add the key ‘optionalFilters’ to the object.
2. Assign the object ‘DY.CS.affinityToAlgolia’ as a value.

index.search({
      query: 'query',
      optionalFilters: DY.CS.affinityToAlgolia
   }).then(res => {
     // console.log(res);
});

var userId = DYO.StorageUtils.get('_dyid','localStorage');
var dyHost = DYO.hosts.rcom;
window.DY.CS = window.DY.CS || {};

getAffinity(DY.scsec, userId, 2)

function getAffinity(section,userId,limit){
var xhr = new XMLHttpRequest();
xhr.open('GET', dyHost + '/userAffinities?limit='+limit+'&sec='+section+(userId?'&uid='+userId:""));
  xhr.onload = function() {
      if (xhr.status === 200) {
          console.log('got user affinity : ' +xhr.responseText);

        DY.CS.affinityAlgolia = DYAffinityToAlgoliaFilter(JSON.parse(xhr.responseText));
      }
      else {
          console.log('error getting affinity');
      }
  };
  xhr.send();
}

function DYAffinityToAlgoliaFilter(affinities){
  var filter = [];
  if (affinities !== {}){
    for (var affinity in affinities){
      for (var val in affinities[affinity]){
        filter.push(affinity+":"+val+"<score="+affinities[affinity][val]+">")
      }
    }
  }
  return filter;
}

index.search({
  query: 'query',
  ruleContexts: [
    'vip_customer', // Experience A, targeted for VIP customers  
  ]
}).then(res => {
  // console.log(res);
});

index.search({
  query: 'query',
  ruleContexts: [
    'Men', // Experience B , targeted for Men
  ]
}).then(res => {
  // console.log(res);
});

var client = algoliasearch('48Mxxx910', 'd7ec9fe3b15xxxxx00892f0');
var index = client.initIndex('indexName'); // Could be added as variable to the template and then can be changed according to the required use-case sort_by_price_index sort_by_popularity_index - 

// only query string
index.search({
  query: 'query string'
  },
  function searchDone(err, content) {
    if (err) throw err;

    console.log(content.hits);
  }
);

// with params
index.search(
  {
    query: 'query string',
    attributesToRetrieve: ['firstname', 'lastname'],
    hitsPerPage: 50,
  },
  function searchDone(err, content) {
    if (err) throw err;

    console.log(content.hits);
  }
);