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.

Installation

NPM

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

Copy
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.

Copy
<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.

Copy
<script src="https://unpkg.com/svrf@<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.

Copy
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.

Copy
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.

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?

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?

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.

Search

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.

Copy
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));

Get Trending

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.

Copy
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.

Copy
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.

Copy
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.

Copy
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.

Copy
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.

Copy
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.