Skip to content

Migration guide from 2.x.x to 3.x.x

Jump to bottom
Tim Carry edited this page Apr 20, 2016 · 29 revisions

AlgoliaSearch JavaScript client V3 is not backward compatible with V2.

If you have any issue, please contact our team at support@algolia.com.

If you were using the Node.js v1.x.x client, see the Node.js v1.x.x migration guide.

Table of contents

  1. Migrate your code to V3
  2. Where to find the V3?
  3. Initialization
  4. AlgoliaSearchHelper usage
  5. callback conventions
  6. New function signatures
  7. Other breaking changes
  8. New features
  1. Fixes
  2. Misc
  3. Can I still use V2?

Migrate your code to V3

Where to find the V3?

The latest V3 can always be found at //cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js

If you are using npm, Bower, RequireJS, Browserify, webpack, V3 is compatible with all module loaders.

npm install algoliasearch@3 --save
bower install algoliasearch#3 -S

Initialization

V2

new AlgoliaSearch(applicationID, apiKey, opts);

V3

algoliasearch(applicationID, apiKey, opts);

Calling algoliasearch(..) without an applicationID or apiKey will now throw an Error.

If you were providing some options in opts, continue reading.

Removed initialization opts

  • opts.dsnHost - Used to specify a particular Distributed Search Network host.
  • use opts.hosts: [dsnHost, host, host] if you really need it
  • opts.dsn - Used to enable/disable DSN on the client. Now done automatically
  • use opts.hosts: [host, host] if you really need it
  • opts.jsonp - Used to force/disable JSONP fallback. The client is now smart enough to automatically do the switch efficiently.

Renamed initialization opts

  • opts.requestTimeoutInMs is now opts.timeout
  • opts.method is now opts.protocol

initialization opts behavior change

  • opts.protocol (in V2 opts.method) must be used as http: or https:
  • opts.hosts
  • If you pass a hosts list to the JavaScript client it will be used without any changes
  • In V2 we cloned and modified the provided hosts list: shuffling and adding a DSN host. This is no more the case

AlgoliaSearchHelper

The AlgoliaSearchHelper was removed and put into a separate library.

If you were using the AlgoliaSearchHelper, please see the corresponding project for how to use it.

Here's a simple example:

<script src="//cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>
<script src="//cdn.jsdelivr.net/algoliasearch.helper/2/algoliasearch.helper.min.js"></script>
<script>
var client = algoliasearch('GKDHJFHGN', 'kfhjd02dsfklh');

var helper = algoliasearchHelper(client, 'myMainIndex', { 
  facets : ['mainCharacterFirstName', 'year'],
  disjunctiveFacets : ['producer']
});

helper.addDisjunctiveRefine('director', 'Clint Eastword');
helper.addDisjunctiveRefine('director', 'Sofia Coppola');

helper.addRefine('year', '2003');

helper.search('', {}, function(err, content) {
  console.log(err, content);
});
</script>

Callback conventions

V2

index.search(query, function(success, content) {
  // success `true` or `false`
  // content is either the results or an error message
}, params);

V3

index.search(query, params, function(err, content) {
  // err `null` or `Error` object (with a `message` property)
  // content contains the results if no error
});

All asynchronous methods are now using these two conventions:

You can also use promises

Changed function signatures

Due to the change in the callback convention, we modified these functions:

  • index.search
    • V2: index.search(query[, callback|params, delay])
    • V3:
      • index.search(query[, cb])
      • index.search(query[, params, cb])
      • index.search(params[, cb]) where params.query is filled
      • We removed the delay param. Delaying can be done on your side using lodash.debounce
      • index.search is an important function, we made it so it can be used in multiple ways
  • client.getLogs
    • V2: client.getLogs(cb[, offset, length])
    • V3: client.getLogs([offset, length, cb])
  • client.listIndexes
    • V2: client.listIndexes(cb[, page])
    • V3: client.listIndexes([page, cb])
  • client|index.addUserKeyWithValidity
    • V2: client|index.addUserKeyWithValidity(acls, validity, maxQueriesPerIPPerHour, maxHitsPerQuery, cb)
    • V3: client|index.addUserKeyWithValidity(acls, {validity, maxQueriesPerIPPerHour, maxHitsPerQuery}[, cb])
  • client.sendQueriesBatch
    • V2: client.sendQueriesBatch(cb, delay)
    • V3: client.sendQueriesBatch([cb])
    • We removed the delay parameter. Delaying can be done on your side using lodash.debounce.
  • index.addObject
    • V2: index.addObject(content[, callback, objectID])
    • V3: index.addObject(content[, objectID, callback])
  • index.getObject
    • V2: index.getObject(objectID[, callback, attributes])
    • V3: index.getObject(objectID[, attrs, callback])
  • index.browse
    • V2: index.browse(page, cb[, hitsPerPage])
    • V3: index.browse(page[, hitsPerPage, cb])

Other breaking changes

Removed globals

These globals were removed and will throw if you use them:

  • window.AlgoliaSearch
  • window.AlgoliaSearchHelper (see AlgoliaSearchHelper)
  • window.ALGOLIA_VERSION => algoliasearch.version

There's now only one exported global function: algoliasearch, see UMD compatibility to know more.

Removed JSON2.js

In V2 we were previously including JSON2.js as part of our build.

This was done to support browsers like IE7.

If you still need to support browsers not providing JSON.* functions, use this:

<!--[if lte IE 7]>
<script src="//cdnjs.cloudflare.com/ajax/libs/json2/20140204/json2.min.js"></script>
<![endif]-->

New features

UMD compatibility

We now support all major module loaders.

So that you can use our client with:

If you are not using any module loader, no problem it will export the algoliasearch property on the window object.

Browserify

Being CommonJS compatible means that you can now:

npm install algoliasearch --save
var algoliasearch = require('algoliasearch');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function(err, content) {
  console.log(err, content);
});

Promises

The JavaScript client now supports both promises and callbacks for asynchronous calls.

var algoliasearch = require('algoliasearch');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');

index.search('something')
  .then(function success(content) {
    console.log('Success', content);
  })
  .catch(function failure(err) {
    console.log('Failure', err);
  });

The promise implementation is the native Promise from the browser or jakearchibald/es6-promise for browsers not supporting the Promise object.

When using the jQuery build, you will get a jQuery promise.

When using the AngularJS build, you will get an AngularJS promise.

callback AND promise?

No.

If you pass a callback, you won't get a promise. If no callback passed, you get a promise.

Fixes

  • IE10 now uses XHR instead of XDR
  • Do not retry when server sends 4xx or 1xx
  • Distinguish jQuery timeout from error
  • Distinguish AngularJS timeout from error
  • Retry with JSONP when AngularJS or jQuery error on request

Misc

The JavaScript client is now fully tested in many browsers.

Our builds are done with browserify.

Can I still use V2?

Yes. If you are using the V2 of our JavaScript client and do not want to upgrade then you can stick to V2.

We have a V2 branch where we will publish critical updates. They will then be pushed to jsDelivr.

Clone this wiki locally