Svrf API Docs

Node.js / JavaScript

Whether you're looking for a way to add immersive content to your web app or have always wanted to build an immersive application, you need a way to access great 3D and 360º content in a scalable way. The Svrf library allows you to easily add the best augmented reality and virtual reality content to your project.

IE Support

This library uses promises which are not supported by IE11 or older. If you would like or need to support IE11 or older, you must use a polyfill (for example es6-promise.

Installation

NPM

You can install the Svrf-Client for JavaScript using NPM.

npm install svrf --save

CDN

You can also use a CDN hosted version of the Svrf-Client in your project. Add this code snippet near the bottom of your pages, right before the closing </body> tag.

<script src="https://unpkg.com/svrf"></script>

Do you need a specific version of the Svrf-Client? You can add a fixed version number, semver range, or tag to the CDN URL. To learn more about the capabilities of UNPKG visit the documentation.

<script src="https://unpkg.com/[email protected]<version>"></script>

Authentication

Before we make your first request, you have to import the library into your app and create a new instance of the Svrf library and provide your Svrf API Key.

const Svrf = require('svrf');
const svrf = new Svrf('Add your Svrf API Key here');

The library will automatically handle authenticating your Svrf API Key, attaching your Authentication Token to your requests' headers, and renew expired tokens. Optionally, you can set up the library to require manual authentication.

Authentication tokens will be automatically saved in localStorage. If localStorage is not available—such as in Node.js—the library will save the Authentication Token in memory. Optionally, you can provide your own custom token storage methods.

Making API Requests

There are three methods to fetch content from the Svrf API. There's search, that allows your users to enter a query and get back related results. Then there's trending, which provides your users with access to curated immersive content. If you know exactly which piece of content the user needs, you can also media directly by its id.

Let's take a detailed look into how to do all of these.

Setting Request Options

You can set the request options for search and trending requests.

The Svrf library offers enum support so you don't have to remember our enums values for categories, stereoscopic types, and media types. You can access them with the static enums property.

svrf.media.getTrending({type: Svrf.enums.mediaType.PHOTO})
.then(({media}) => {/* only photos are returned */})
.catch((err) => console.error(err));

Let's walk through all of the request options that are available to you.

category string?

Retrieve a specific category of Media.

Category enum

We suggest using the Category enum. For example, to get the Face Filters category, use Svrf.enums.category.FACE_FILTERS.

hasBlendShapes boolean?

Request 3D Media that has or does not have blend shapes.

isFaceFilter boolean?

Set to true to retrieve only face filter 3D Media.

minimumWidth number?

Deprecated

360 photos and 360 videos are no longer supported on Svrf.

pageNum number?

To fetch the next page of search results, use the nextPageNum returned from the previous page in the pageNum option value.

requiresBlendShapes boolean?

3D models, specifically face filters, that require blend shapes are best experienced when blend shape animations are active. We strongly suggest that any 3D models where requiresBlendShapes is true must incorporate blend shape animations in their application to ensure the user has a high-quality experience.

If you'd like to use face filters without blend shapes, we strongly urge you to set this option to false.

size number?

To adjust the quantity of Media returned, adjust the size option. Requests are limited to 100 Media per request.

stereoscopicType string?

Deprecated

Stereoscopic 360 photos and 360 videos are no longer supported on Svrf.

type string? | string[]?

In the request options, you can set the type options to an Array of MediaTypes: 3d, photo, and video, or you can omit it to get all types of media.

MediaType enum

We suggest using the MediaType enum. For example, to get photos, use Svrf.enums.mediaType.MODEL_3D.

Deprecated

360 photos and 360 videos are no longer supported on Svrf.

The svrf.media.search() method brings the power of immersive search found on Svrf.com to your app or project. Svrf's search engine enables your users to instantly find the immersive experience they're seeking. Content is sorted by the Svrf rating system, ensuring that the highest quality content and most prevalent search results are returned.

const query = 'puppies';
svrf.media.search(query)
.then((res) => {
const mediaArray = res.media;
// Do what you want with the Media[]
})
.catch((err) => console.error(err));

The svrf.media.getTrending provides your app or project with the hottest immersive content. The experiences returned mirror Svrf, from timely cultural content to trending pop-culture references. The trending experiences are updated regularly by human curators to ensure users always get fresh updates of immersive content.

svrf.media.getTrending()
.then((res) => {
const mediaArray = res.media;
// Do what you want with the Media[]
})
.catch((err) => console.error(err));

Pagination

Fetching the next page of results can be done by setting the pageNum option for search and trending requests.

let nextPageNum;
function search (query) {
if (!query) {
throw new Error('a search query is required');
}
return svrf.media.search(query, {pageNum: nextPageNum})
.then((res) => {
const mediaArray = res.media;
// Do what you want with the Media[]
nextPageNum = res.nextPageNum;
})
.catch((err) => console.error(err));
}

Get Media

To get a specific piece of media from Svrf by ID, use the svrf.media.getById() method.

In this example, we're fetching Media with ID 547963.

svrf.media.getById('547963')
.then((res) => {
const media = res.media;
// Do what you want with the Media
})
.catch((err) => console.error(err));

Advanced Settings

When initializing a new instance of the Svrf library, you have the option to set advanced options.

const Svrf = require('svrf');
const options = {
// Set advanced options
};
const svrf = new Svrf('Add your Svrf API Key here', options);

Manual Authentication

When you create a new Svrf instance, the library will automatically authenticate your Svrf API Key.

However, you may want to postpone the initial authentication request and manually control when the Svrf API Key is authenticated. In that case, you can set isManualAuthentication option to true. Then call svrf.authenticate() manually whenever you want.

const Svrf = require('svrf');
const options = {
isManualAuthentication: true,
};
const svrf = new Svrf('Add your Svrf API Key here', options);
// Let's say we know that user is IDLE and we have time to make an auth request.
svrf.authenticate();
svrf.media.getTrending()
.then(({media}) => {/* you've got the best of the best media! */})
.catch((err) => console.error(err));

Custom Token Storage

The library will automatically attempt to save the Authentication Token in localStorage. If localStorage is not available—such as in Node.js—the library will save the Authentication Token in memory.

However, you may want to store the token in a different way. The library allows you to use custom methods to store your Authentication Token. You can pass an object that implements get, set, and clear methods as an option when initializing the library.

const Svrf = require('svrf');
const options = {
storage: {
get: () => {
return yourCustomStorage.read();
},
set: (value) => {
return yourCustomStorage.write(value);
},
clear: () => {
return yourCustomStorage.clear();
},
},
};
const svrf = new Svrf('Add your Svrf API Key here', options);

Note that set is going to be called with an object. An equal object should be returned from the get method.