-
Notifications
You must be signed in to change notification settings - Fork 222
Migration guide from 2.x.x to 3.x.x
AlgoliaSearch JavaScript client V3 is not backward compatible with V2.
If you have any issue, please contact our team at [email protected].
- V2 and V3 examples
- Breaking changes
- new AlgoliaSearch() → algoliasearch()
- Removed globals
- AlgoliaSearchHelper
- Callback convention
- Changed function signatures
- Removed JSON2.js
The V3 release can be summarized in this example:
var client = new AlgoliaSearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function(success, content) {
// success is true if success or false if error
// content contains either the results (JS Object) or the error (JS Object)
console.log(success, content);
});
We changed the way we initialize and do callbacks in V3.
// no more `new AlgoliaSearch(..)` constructor
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');
index.search('something', function(err, content) {
// err is null if success or an `Error` object if failure
// content contains the results or `undefined` if failure
console.log(err, content);
});
Now let's see in detail what changed.
As we saw it, you must now use algoliasearch('applicationID', 'apiKey'[, opts])
to initialize an API client.
If you call algoliasearch(..)
without an applicationID
or apiKey
, it will throw
.
-
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.
-
opts.requestTimeoutInMs
is nowopts.timeout
-
opts.method
is nowopts.protocol
-
opts.protocol
(in V2opts.method
) must be used ashttp:
orhttps:
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
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.
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/1/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>
All asynchronous methods are now using these two conventions:
- callback is always the last parameter
- callback is called with
cb(err, content)
to comply to the popular asynchronous JavaScript convention
You can also use promises
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])
- V2:
-
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])
Removed JSON2.js
In ᵛ² 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]-->
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.
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);
});
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.
No.
If you pass a callback, you won't get a promise. If no callback passed, you get a promise.
- 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
The JavaScript client is now fully tested in many browsers.
Our builds are done with browserify.
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.