Revieve SDK

This is the documentation and demo page of Revieve SDK.


Current version: 1.8 view changelog

Try the LIVE AR module Try the AR module Try the PR module
Live Video Augmented Reality (liveAR) Demo
Access to the liveAR demo page

See what our SDK is able to do with Live Video Augmented Reality module

Try it!
New!
Augmented Reality (AR) Demo
Access to the AR demo page

See what our SDK is able to do with Augmented Reality module

Try it!
Product recommendations (PR) Demo
Access to the PR demo page

See what our SDK is able to do with Product Recommendations module

Try it!
SDK Documentation
Access to SDK documentation

Know how you can work with our SDK

SDK docs

You can start using Revieve SDK by adding it in your project with this code:

              
  <script src="https://sdk.revieve.com/revieve-sdk.min.js"/>
              

Or you can import the SDK class with this code:


  npm install @revieve/sdk --save
            

  import RevieveSDK from '@revieve/sdk';
            


Modular architecture

Revieve SDK has a modular architecture to manage each functionality provided. There are three modules available:

  • CV: Computer Vision module. This module is the one in charge to manage the user image and communicates with our servers to perform skin analysis from the user image. It will store all the information retrieved from the server
  • AR: Augmented Reality module. This module will manage all the effects and rendering them. It applies them to the same picture that was analyzed in the CV module.
  • liveAR: Live Video Augmented Reality module. This module renders effects over live video. It applies makeup effects to live video taken from the webcam bringing the opportunity to try in real time products over your face.
  • PR: Product Recommendations module. This module uses all the user preferences you've given, CV module results, environmental data to get a set of best matching products from the Revieve Product API.
  • Analytics: module to track user interactions with the SDK.
CV
Module
AR
Module
Live AR
Module
PR
Module
Analytics Module

Note that you will need to access each module to execute methods or get information.


Quick start guide (AR example)

First of all you need to get a new instance of the RevieveSDK, using this code


  let revieveSDK = new RevieveSDK('XXXXXXXX', true);
          

First parameter is your partnerID and second parameter is a boolean that defines if you are connecting to test environment. True means that you are connecting to test environment.

If you want to connect to production environment then you need to instantiate the SDK like this:


  let revieveSDK = new RevieveSDK('XXXXXXXX', false, 'prod');
          

After that you can define your user ID


  revieveSDK.setUserId('XXXXXXXXXX');
          

The userId is used for identifying the user so if user has accepted cookies, its possible to set it from a browser cookie for instance, generating random UID for each visitor on the first time they come. If the user doesn't accept cookies you should set it to a static variable, for example 'anonymous-web-user'.

Before analyzing an image you must set the gender using this method


  revieveSDK.setGender(RevieveSDK.gender.FEMALE);
          

Then you need to make additional configuration to get all the information you need from the backend setting up the components object into the SDK configuration. Please keep in mind that you will need to specify a proper components set to be able to use highlihgt and get methods. Please consult components configuration section.

        
  let components = [
    'eyes',
    'wrinkles',
    'redness',
    'shine',
    'acne',
    'texture',
    'smoothness',
    'hyperpigmentation',
    'melasma',
    'freckles',
    'dark_spots',
    'dull_skin',
    'radiance',
    'uneven_skin_tone',
    'makeup',
    'masks',
    'ar_landmarks',
    'ar_coordinates',
    'acne_visualization',
    'wrinkles_visualization',
    'shine_visualization',
    'hyperpigmentation_visualization',
    'freckles_visualization',
    'dark_spots_visualization',
    'melasma_visualization',
    'uneven_skin_tone_visualization',
    'hair'
  ];
  revieveSDK.setConfiguration({ components });
                  
                

SDK setup is done. In case of our AR example, now you are ready to send and analyze an image.


  revieveSDK.CV.setImage(imageFile).then(() => {
    revieveSDK.CV.analyzeImage()
      .then(() => {
          .....
      })
  })
          

Please take note that both methods returns a promise and you need to wait until promises get solved to continue. Regarding the image, the minimum resolution is 600px, so you need to ensure image has at least 600px of height or width before send it to the server.

Now you are ready to use the AR methods to highlight each finding. You can set the container of the element where the result image will be rendered with this method.


  revieveSDK.AR.setContainer('XXXXXXXX');  
        

where there parameter represents the ID of the DOM element that will be used to render the result image.

Now you can get the values and highlight each finding:

  • oiliness-> value: revieveSDK.CV.getSkinShine() / highlight: revieveSDK.AR.highlightSkinShine()
  • wrinkles -> value: revieveSDK.CV.getWrinkles() / highlight: revieveSDK.AR.highlightWrinklesIndividually()
  • texture -> value: revieveSDK.CV.getTexture()/ highlight: revieveSDK.AR.highlightTexture()
  • redness -> value: revieveSDK.CV.getRedness() / highlight: revieveSDK.AR.highlightRedness()
  • hyperpigmetation -> value revieveSDK.CV.getHyperpigmentation()/ highlight: revieveSDK.AR.highlightHyperpigmentationIndividually()
  • etc...

You can dehighlight previous effects with revieveSDK.AR.dehighlightAll()

All the highlight methods (included the dehighlightAll method) return a promise that when is solved you will have an object that has a CSS style object for in and out effect that you can apply to the container and that will helps you to animate the transition between highlight and dehighlight state. For example, if you want to apply a css style when you dehighlight an effect


  this.state.sdk.AR.dehighlightAll().then(animation => {
      this.setState({
        ARAnimation: animation.out
      });
    });
  ...
  

The animation is based on a zoom to the selected area / areas. You can modify the scale factor for this zoom using the setScaleFactor method.


  revieveSDK.AR.setScaleFactor(1.1); // It will increase 10% the zoom
        

State object

Revieve SDK manage all the information shared between modules in a state object. This JSON object has information about:

  • partnerID: A valid partner ID obtained from revieve. If you don't have a valid ID, please contact with us by email at info@revieve.com
  • userID: A user ID to identify queries in PR module.
  • apiVersion: API version to use in CV module. Currently there are two versions available: '2' and '3'. By default, is setted the last version available.
  • configuration: Object to store all the values provided by user and used to, for example, filter the product recomendations in PR module.

You can get the current state of the SDK throught the getState method and use this to render your user interface.


Initializing the SDK

You can initialize the library by instantiating a new RevieveSDK object. Please note that constructor needs:

  • partnerID assigned to your organization by Revieve.
  • testing(optional) boolean that let the SDK know if you want to connect to test environment. If you don't specify any value, you will connect to test environment.
  • environment(optional) if you set testing to false, you can specify the environment you want to connect (test, prod, etc.)
  • disableUsageAnalytics(optional) flag for disable telemetry. Defaults to false.

  let revieveSDK = new RevieveSDK('XXXXXXXX', true);
          

To ensure Computer Vision module gets correct result for eye color and skin undertone, you can set a skintone value to SDK configuration. Setting skintone will also result in more realistic AR effects. If you don't need these features, you don't have to set the skintone. You can do it with this code:


  revieveSDK.setSkintone(skintone);
          

Important note for API version 3 and above You don't need to specify the skintone because it is detected automatically by the CV module

As parameter you need to specify a value between 1 and 6 to define user's skin tone in Fitzpatrick scale.

You can set the userID information to the SDK state with this code:


  revieveSDK.setUserId('XXXXXXXXX');
          

You can set the api version to use in CV module with this code:


  revieveSDK.setApiVersion('2');
          

Please note that by default you will use the last version of the API available, so it's not necessary to set this value if you want to use the last version.

SDK uses a set of lists and default values to work properly. You can consult their values with this static properties:

  • RevieveSDK.gender: List of genders acepted by the SDK.
  • RevieveSDK.skinTypes: List of skin types acepted by the SDK.
  • RevieveSDK.masks: List of masks available for the API version selected.
  • RevieveSDK.defaultStrength: Default strength for AR effects.
  • RevieveSDK.makeupMeasures: JSON structure with makeupMeasures accepted by the SDK.

Some visualization methods, as individual wrinkles or hyperpigmentation spots visualization, need special configuration to work. You need to set up needed components using setConfiguration method and components array


  let components = [
    'eyes',
    'wrinkles',
    'redness',
    'redness_visualization',
    'shine',
    'acne',
    'texture',
    'texture_visualization',
    'smoothness',
    'hyperpigmentation',
    'melasma',
    'freckles',
    'dark_spots',
    'dull_skin',
    'radiance',
    'uneven_skin_tone',
    'makeup',
    'masks',
    'ar_landmarks',
    'ar_coordinates',
    'acne_visualization',
    'wrinkles_visualization',
    'shine_visualization',
    'hyperpigmentation_visualization',
    'freckles_visualization',
    'dark_spots_visualization',
    'melasma_visualization',
    'uneven_skin_tone_visualization',
    'pore_dilation',
    'skin_firmness',
    'skin_sagging',
    'skin_sagging_visualization',
    'hair'
  ];
  revieveSDK.setConfiguration({ components });
        

These are available components:

  • eyes -> component to get information related with eyes as eyebags and dark circles
  • wrinkles -> component to get information related with wrinkles.
  • wrinkles_visualization -> component to get information needed to use highlightWrinklesIndividually method.
  • redness -> component to get information related with redness.
  • redness_visualization -> component to get information needed to use highlightRednessIndividually method.
  • hyperpigmentation -> component to get information related with hyperpigmentation.
  • hyperpigmentation_visualization -> component to get information needed to use highlightHyperpigmentationIndividually method.
  • melasma -> component to get information related with melasma.
  • melasma_visualization -> component to get information needed to use highlightMelasmaIndividually method.
  • freckles -> component to get information related with freckles.
  • freckles_visualization -> component to get information needed to use highlightFrecklesIndividually method.
  • dark_spots -> component to get information related with dark spots.
  • dark_spots_visualization -> component to get information needed to use highlightDarkSpotsIndividually method.
  • texture -> component to get information related with texture.
  • texture_visualization -> component to get information needed to use highlightTextureIndividually method.
  • smoothness -> component to get information related with smoothness.
  • dull_skin -> component to get information related with dull skin.
  • radiance -> component to get information related with radiance.
  • makeup -> component to get information related with makeup as face shape, eye color, skin undertone, skin foundation RGB and fitzpatrick scale
  • shine -> component to get information related with skin shine.
  • shine_visualization -> component to get information needed to use highlightSkinShine method.
  • acne -> component to get information related with acne.
  • acne_visualization -> component to get information needed to use highlightAcneIndividually method.
  • uneven_skin_tone -> component to get information related with uneven skin tone.
  • uneven_skin_tone_visualization -> component to get information needed to use highlightUnevenSkinToneIndividually method.
  • pore_dilation -> component to get information related with pore dilation.
  • pore_dilation_visualization -> component to get information needed to use highlightPoreDilationIndividually method.
  • skin_firmness -> component to get information related with skin firmness.
  • skin_sagging -> component to get information related with skin sagging.
  • skin_sagging_visualization -> component to get information needed to use highlightSkinSaggingIndividually method.
  • hair -> component to get information related with hair.
  • masks -> component to get mask information into each of the above components. If you don't add this component you won't be able to use highlight methods.

It's important to configure properly the needed components for performance reasons. AnalyzeImage method response size depends on how much components are you requesting for. For example, if you aren't going to use the acne information, then you don't need to add it to the components and then the analyzeImage response will be shorter and you will need less time to get it.


Computer Vision module (CV module)

You will need to interact with CV module when you want to analyze an image and get all the information related to it from our CV API. This information includes all the skin areas and possible skin problems detected in the picture.

To start using the CV module you need to set an image with this code:


  revieveSDK.CV.setImage(image)
  .then(()=>{
    ...
  })
  .catch(()=> {
    ...
  });
          

setImage method gets one parameter that is the image to be analyzed and it can be in Base64 format or HTML file object. File uploaded must have at least 600x600 resolution.

Please note that setImage is an asynchronous method and it returns a promise. Establishing the image does not launch the process of analysis.

After setting image correctly, you can start the analyze process with this code:


  revieveSDK.CV.analyzeImage()
  .then(()=>{
    ...
  })
  .catch(()=> {
    ...
  });
        

Please note that setImage is an asynchronous method and it returns a promise.

After skin analysis process ends, you will have all the information available in the state of the module. You can access this information throught these methods:

  • getState: get complete state object of the CV module. Note that this state is different of SDK state and stores all the CV specific information.
  • hasError: control method to determine if there was any errors during the analysis process. You can check the details of the error with getStatus method.
  • getStatus: method to get all warnings and errors during the analysis process.
  • getResults: method to get full JSON results from server. It includes information about skin problems detected.
  • getMasks: get the set of areas detected in the image. The complete set of possible areas can be accessed through RevieveSDK.masks
  • getImage: get the original image set in CV module
  • getAnonymizeImage: get anonymized original image. Please take note that you need "eyes" component configured to get the needed information by this method
  • getWrinkles: get the value detected for wrinkles by our CV API
  • getRedness: get the value detected for redness by our CV API
  • getHyperpigmentation: get the value detected for hyperpigmentation by our CV API
  • getMelasma: get the value detected for melasma by our CV API
  • getFreckles: get the value detected for freckles by our CV API
  • getDarkSpots: get the value detected for dark spots by our CV API
  • getSmoothness: get the value detected for smoothness by our CV API
  • getRadiance: get the value detected for radiance by our CV API
  • getDullSkin: get the value detected for dull skin by our CV API
  • getUnevenSkinTone: get the value detected for uneven skin tone by our CV API
  • getEyebags: get the value detected for eyebags by our CV API
  • getDarkcircles: get the value detected for darkcircles by our CV API
  • getTexture: get the value detected for texture by our CV API
  • getSkinShine: get the value detected for skin shine by our CV API
  • getAcne: get the value detected for acne by our CV API
  • getPoreDilation: get the value detected for pore dilation by our CV API
  • getSkinSagging: get the value detected for skin sagging by our CV API
  • getSkinFirmness: get the value detected for skin firmness by our CV API
  • getFaceShape: get face shape detected by our CV API
  • getEyeColor: get eye color detected by our CV API
  • getSkinUndertone: get skin undertone detected by our CV API
  • getFindings: you can get all the information of findings of our CV API with this method. It returns a JSON structure with information detected (wrinkles, hyperpigmentation, etc.) and areas where this information are present.
  • getSkinFoundation: you can get all the information related with skin foundation detected by CV API with this method. It returns a JSON structure with information detected: rgb and hex skin tone colour and skintone value detected.
  • getHairVolume: get the value detected for hair volume by our CV API
  • getHairFrizziness: get the value detected for hair frizziness by our CV API
  • getHairType: get the value detected for hair type by our CV API

Augmented Reality module (AR module)

IMPORTANT!!! To use the AR module you will need to use the CV module to set image and analyze it before starting to apply filters within AR module.

Apply effects on the image automatically based on your product details or based on user input.

Due to the huge amount of methods available in this module, you can access to helper property methods, that has all methods available in AR module clasified in five groups:

  • configuration Methods to cofigure the behaviour of the module.
  • control Methods to control the flow of the module, like redraw effects, etc.
  • highlight Methods to apply highlight effects.
  • skincare Methods to apply skincare effects.
  • makeup Methods to apply makeup effects.
  • product Methods to interact with product visualization.

If you want to apply effect automatically to a HTML container, you can use the method setContainer with this code:


  revieveSDK.AR.setContainer ( 'containerIdElement' );
          

Please note that if you set a containerId, effects will be re-rendered automatically when window resize. If you don't want to add this re-render process, you need to call to setContainer as follows:


  revieveSDK.AR.setContainer ( 'containerIdElement', true); // disable auto re-render effects on window resize
          

You can define how image and effects will fit to container's dimensions with method setOrientation. By default it will auto fit the image so no need to change the value. If you set to landscape image and effects will set to container's width. If you set to portrait they will fit to container's height. By default, SDK will set auto option.


  revieveSDK.AR.setOrientation ( 'landscape' );
          

AR module has a white balance correction system to adjust the filters applied into the original picture based on white balance information to make it more natural. All the white balance correction information is managed automatically by the CV module, but if you want to modify it using method setWhiteBalanceCorrection. This method accept an array parameter with three components with correction values for: red, blue and luminance.

There are effects applied automatically to predefined areas like eyes. These methods are:

  • reduceEyebags
  • reduceCrowsFeet
  • reduceDarkcircles

The parameter sets strength for the effect:

  • 1.0 Applies maximum AR effect to counteract Eyebags, Dark circles, etc.
  • 0.0 Applies no effect to counteract Redness, Eyebags, Dark circles, etc.

  revieveSDK.AR.reduceCrowsFeet ( 0.2 );
  revieveSDK.AR.reduceDarkcircles ( 0.4 );
  revieveSDK.AR.reduceCrowsFeet( 0 );
          

There are core methods that can be applied to a set of areas in the image. These methods are:

  • reduceRedness
  • reduceHyperpigmentation
  • reduceWrinkles
  • brightenSkin

First parameter sets strength for the effect and second parameter sets the mask to apply the effect on. The possible values for this parameter are specified in RevieveSDK.masks property and it depends on the API Version configured. The values are for V2:

  • RevieveSDK.masks.SKIN: 'Skin'
  • RevieveSDK.masks.FOREHEAD: 'forehead'
  • RevieveSDK.masks.FOREHEAD_WORRY_LINES: 'forehead worry lines'
  • RevieveSDK.masks.BETWEEN_BROWS_FROWN_LINES: 'between-brows frown lines'
  • RevieveSDK.masks.NOSELINE_BUNNY_LINES: 'noseline bunny lines'
  • RevieveSDK.masks.LEFT_SIDE_EYE_CROWS_FEET: 'left side eye crow's feet',
  • RevieveSDK.masks.RIGHT_SIDE_EYE_CROWS_FEET: 'right side eye crow's feet'
  • RevieveSDK.masks.LEFT_SIDE_TEARLINE: 'left side tearline'
  • RevieveSDK.masks.RIGHT_SIDE_TEARLINE: 'right side tearline'
  • RevieveSDK.masks.LEFT_EYEBAG: 'left eye bag'
  • RevieveSDK.masks.RIGHT_EYEBAG: 'right eye bag'
  • RevieveSDK.masks.EYEBROWS: 'Eyebrows'
  • RevieveSDK.masks.LEFT_CHEEK: 'left cheek'
  • RevieveSDK.masks.RIGHT_CHEEK: 'right cheek'
  • RevieveSDK.masks.LIPS: 'Lips'

And for V3 (please note that structure has changed. Now you have different masks for skincare and makeup) are:

  • RevieveSDK.masks.skincare.SKIN: 'Skin'
  • RevieveSDK.masks.skincare.FOREHEAD: 'forehead'
  • RevieveSDK.masks.skincare.FOREHEAD_WORRY_LINES: 'forehead worry lines'
  • RevieveSDK.masks.skincare.BETWEEN_BROWS_FROWN_LINES: 'between-brows frown lines'
  • RevieveSDK.masks.skincare.LEFT_SIDE_EYE: 'left side around the eye'
  • RevieveSDK.masks.skincare.RIGHT_SIDE_EYE: 'right side around the eye'
  • RevieveSDK.masks.skincare.LEFT_SIDE_EYE_CROWS_FEET: 'left side eye crow's feet',
  • RevieveSDK.masks.skincare.RIGHT_SIDE_EYE_CROWS_FEET: 'right side eye crow's feet'
  • RevieveSDK.masks.skincare.LEFT_EYEBAG: 'left eye'
  • RevieveSDK.masks.skincare.RIGHT_EYEBAG: 'right eye'
  • RevieveSDK.masks.skincare.LEFT_UNDER_EYE: 'left under-the-eye region'
  • RevieveSDK.masks.skincare.RIGHT_UNDER_EYE: 'right under-the-eye region'
  • RevieveSDK.masks.skincare.LEFT_SIDE_TEARLINE: 'left side tearline'
  • RevieveSDK.masks.skincare.RIGHT_SIDE_TEARLINE: 'right side tearline'
  • RevieveSDK.masks.skincare.LEFT_CHEEK: 'left cheek'
  • RevieveSDK.masks.skincare.RIGHT_CHEEK: 'right cheek'
  • RevieveSDK.masks.skincare.NOSE: 'nose'
  • RevieveSDK.masks.skincare.NOSELINE_BUNNY_LINES: 'noseline bunny lines'
  • RevieveSDK.masks.skincare.LEFT_SIDE_MOUTH: 'left side around mouth'
  • RevieveSDK.masks.skincare.RIGHT_SIDE_MOUTH: 'right side around mouth'
  • RevieveSDK.masks.skincare.CHIN: 'chin'
  • RevieveSDK.masks.skincare.LEFT_SIDE_NASOLABIAL: 'left side nasolabial line'
  • RevieveSDK.masks.skincare.RIGHT_SIDE_NASOLABIAL: 'right side nasolabial line'
  • RevieveSDK.masks.skincare.LEFT_SIDE_MARIONETTE: 'left side marionette line'
  • RevieveSDK.masks.skincare.RIGHT_SIDE_MARIONETTE: 'right side marionette line'
  • RevieveSDK.masks.skincare.VERTICAL_LIP_LINES: 'vertical lip lines'
  • RevieveSDK.masks.skincare.RIGHT_LOWER_FACE: 'right lower face'
  • RevieveSDK.masks.skincare.LEFT_LOWER_FACE: 'left lower face'
  • RevieveSDK.masks.makeup.EYEBROWS: 'Eyebrows'
  • RevieveSDK.masks.makeup.EYEBROWS: 'Eyebrows'
  • RevieveSDK.masks.makeup.LEFT_CHEEK: 'Left cheek'
  • RevieveSDK.masks.makeup.RIGHT_CHEEK: 'Right cheek'
  • RevieveSDK.masks.makeup.NOSE: 'Nose'
  • RevieveSDK.masks..makeup.LIPS: 'Lips'

  revieveSDK.AR.reduceRedness ( 0.5, [RevieveSDK.masks.LEFT_CHEEK, RevieveSDK.masks.RIGHT_CHEEK] );
  revieveSDK.AR.reduceHyperpigmentation ( 0.8, [RevieveSDK.masks.FOREHEAD, RevieveSDK.masks.RIGHT_CHEEK] );
  revieveSDK.AR.brightenSkin ( 0.2, [RevieveSDK.masks.FOREHEAD]);
          

There are makeup methods that can be applied specifying the color of, for example, lipstick. These methods are:

  • applyLipstick
  • applyBlush
  • applyFoundation
  • applyEyeshadow
  • applyEyeliner
  • applyLipliner

First parameter sets strength for the effect and second parameter sets the rgb, hex code or name of the color to apply.


  revieveSDK.AR.applyLipstick ( 0.8, 'red' );
  revieveSDK.AR.applyBlush ( 0.4, '#ee2378' );
  revieveSDK.AR.applyFoundation( 0.5, '#edb576' );
  revieveSDK.AR.applyEyeshadow( 0.5, '#e4b880' );
  revieveSDK.AR.applyEyeliner( 0.9, '#000000' );
  revieveSDK.AR.applyLipliner( null, '#5b0d0d' ); // apply it with default strength
          

Please note that all apply effect methods are asynchronous and returns a promise.

When you apply some efect, if you specified a valid container ID with setContainerId method, the results will be rendered in the container automatically. However, you can access to the results div throught method getResultsDiv with this code:


  revieveSDK.AR.getResultsDiv ();
          

Or you can get a JPG image with the results using the getResultsImage method with this code:


  revieveSDK.AR.getResultsImage ();
          

You can reset the effects applied using reset method.

You can redraw all the effects applied until now with redrawEffects method.

Also, you can highlight the different problems detected by CV API with the next methods. All methods (except highlight area values and individually ones) accepts two parameters: an array with masks where you want to highlight the problem and the second parameter can be a color to be used to darken the rest of the picture when we are highlighting an area or an object that let you to customize the way areas are highlight. The object has this properties:

  • fill: object with one property color that defines the color to fill the area. Color is declared as sting.
  • stroke: object with three properties:
    • color: defines the color of the line. Color is declared as sting.
    • width: defines the the width of the line.
    • lineDash: array with two dimensions. First defines the width and second one the space between segments. Both values are numbers and define pixels.
Keep in mind that both properties are optional. You can define just fill, just stroke or both.
Note that if you set an empty or null masks array, the worst area detected by CV module will be highlighted.

The methods to highlight a problem are:

  • highlightDarkcircles: highlight the areas specified by masks that has darkcircles problems.
  • highlightDarkcirclesAreaValues: show circles to know what is the state of darkcircles on each individual area.
  • highlightEyebags: highlight the areas specified by masks that has eyebags problems.
  • highlightEyebagsAreaValues: show circles to know what is the state of eyebags on each individual area.
  • highlightHyperpigmentation: highlight the areas specified by masks that has hyperpigmentation problems.
  • highlightHyperpigmentationIndividually: highlight the worst hyperpigmentated points detected by CV.
  • highlightHyperpigmentationAreaValues: show circles to know what is the state of hyperpigmentation on each individual area.
  • highlightMelasma: highlight the areas specified by masks that has melasma problems.
  • highlightMelasmaIndividually: highlight the melasma areas detected by CV.
  • highlightMelasmaAreaValues: show circles to know what is the state of melasma on each individual area.
  • highlightFreckles: highlight the areas specified by masks that has freckles problems.
  • highlightFrecklesIndividually: highlight the freckles detected by CV.
  • highlightFrecklesAreaValues: show circles to know what is the state of melasma on each individual area.
  • highlightDarkSpots: highlight the areas specified by masks that has dark spots problems.
  • highlightDarkSpotsIndividually: highlight the dark spots detected by CV.
  • highlightDarkSpotsAreaValues: show circles to know what is the state of melasma on each individual area.
  • highlightRedness: highlight the areas specified by masks that has redness problems.
  • highlightRednessIndividually: highlight the areas with redness problems detected by CV.
  • highlightRednessAreaValues: show circles to know what is the state of redness on each individual area.
  • highlightTexture: highlight the areas specified by masks that has texture problems.
  • highlightTextureIndividually: highlight the areas with texture problems detected by CV.
  • highlightTextureAreaValues: show circles to know what is the state of texture on each individual area.
  • highlightWrinkles: highlight the areas specified by masks that has wrinkles problems.
  • highlightWrinklesIndividually: highlight the worst wriknles detected by CV.
  • highlightWrinklesAreaValues: show circles to know what is the state of wrinkles on each individual area.
  • highlightUnevenSkinTone: highlight the areas specified by masks that has uneven skin tone problems.
  • highlightUnevenSkinToneIndividually: highlight the uneven skin tone areas detected by CV.
  • highlightUnevenSkinToneAreaValues: show circles to know what is the state of uneven skin tone on each individual area.
  • highlightSmoothness: highlight the areas specified by masks that has smoothness problems.
  • highlightSmoothnessAreaValues: show circles to know what is the state of smoothness on each individual area.
  • highlightSkinShine: highlight the areas with high skin shine values.
  • highlightAcne: highlight the areas specified by masks that has acne problems.
  • highlightAcneIndividually: highlight the worst acne points detected by CV.
  • highlightAcneAreaValues: show circles to know what is the state of acne on each individual area.
  • highlightSkinSaggingIndividually: highlight the areas with skin sagging problems detected by CV.

Also, you can highlight general information about CV results with this methods:

  • highlightFaceShape: highlight the face shape detected by the CV module. This method accepts one parameter to set the color to be used to draw the face shape.
  • highlightEyesArea: highlight the eyes area. This method doesn't require any parameter.
  • highlightCheekArea: highlight the cheek area. This method doesn't require any parameter.
  • highlightSkinUndertone: highlight the cheek area with the skin undertone information detected by CV module.
  • highlightSkinFoundation: highlight the cheek area with the skin foundation information detected by CV module.
  • highlightEyeColor: highlight the eyes area with the eye color information detected by CV module.

You can revert the highlight effect with method dehighlightAll

All the effect method returns a promise. When this promise is resolved, it returns a style object to be applied if you want to animate the effect. You can see an example in the AR module test page.

The style object contains an animation that is based on a zoom to the selected area / areas. You can modify the scale factor for this zoom using the setScaleFactor method.


  revieveSDK.AR.setScaleFactor(1.1); // It will increase 10% the zoom 
          
PR module interactions

You can visualize the associated effect of a product return by PR module getRecommendedProducts method with this code:


  revieveSDK.AR.visualizeProduct(product); // to visualize a product with default strength
          

You can set the strength of the effect setting up the parameter. If you want to remove the effect applied by a product, you can call this method with strength equalt to 0.


  revieveSDK.AR.visualizeProduct(product, 0.8); // to visualize a product with 0.8 strength
  revieveSDK.AR.visualizeProduct(product, 0); // to remove a product effect
          

This method accepts one parameter that is a JSON structure with the specific product information. You can get this information using the getRecommendedProducts of PR module.

This method returns a promise.

Please note, not all the products returned by getRecommendedProducts could be visualize by AR module. To know if a product could be visualize you can use this code:


  revieveSDK.AR.canVisualizeProduct(product);
          

Live Video Augmented Reality module (liveAR module)

With this module you can apply makeup effects in real time over a video source. You need to initialize the module to start interacting with it. To initialize it you can use this code:


  revieveSDK.liveAR.initialize({
    renderToSelector,
    debug,
    effects,
    advanceTracking,
    eventHandler,
    faceMask
  })
          

As you can see to initialize the module you need to setup a parameter that is a JSON object with following properties:

  • renderToSelector: CSS selector that defines the HTML element where the video and effects will be rendered into. Please take note that if this element has some element inside, all these elements will be removed.
  • debug: (OPTIONAL) boolean flag to activate advance loging info. Disabled by default.
  • effects: (OPTIONAL) initial configuration for effects. If you don't define any effect, no effects will be rendered in video initially. Please check the effect JSON structure above to know how interact with effects.
  • advanceTracking: (OPTIONAL) boolean to activate the advance tracking option in liveAR. With this option you will have a more accurate points and effects. Please take note that you need a special license to use this option.
  • eventHandler: (OPTIONAL) Function to handler events emitted by the module as changes during initilization process. Please check live AR demo source code to know more about it.

To render effects into the video, you just need to use this method:


  revieveSDK.liveAR.changeEffects(effects)
          

The effects parameter is a JSON object that defines the effects you want to render into the video. The structure of this JSON is:

  • Product category: makeup product category. For now, available product categories are: mascara, eyeshadow, eyeliner, blush, lipstick, lipliner concealer, bronzer, highlighter and foundation. There are two additional effect types: beautify that smooths the skin of the face and eyebrows that brings us the option to change the shape of the eyebrow. For each category, you can define the effect to be rendered.
  • Inside each category:
    • enabled: boolean flag to define if effect is enabled or don't.
    • color: array that defines the color's R,G,B values. In case of eyeshadows you can define a color palette using an array of 3 colors (array of 3 arrays)
    • strength: number between 0 and 1 that defines the strength of the effect.
    • In case of define a lipstick effect:
      • finish: finish to apply to the effect. Available finishes are: natural, gloss, matted, metallic, frost and satin
      • finishStrength: number between 0 and 1 that defines the strength of the finish.
    • In case of define lipliner:
      • thickness: number that defines the thickness (in pixels) of the line.
    • In case of define eyeshadow:
      • type:type of eyeshadow to apply. Keep in mind that you should define a color palette (array of colors) in color property to emulate it properly. Available types are: 'variant1', 'variant2', 'variant3', 'variant4' and 'variant8'
      • finish:finish of the eyeshadow to apply. Available finishes are: 'glitter', 'shimmer', 'frost', 'metallic' and 'matte'
    • In case of define eyeliner:
      • type:type of eyeliner to apply. Available types are: 'classic', 'everyday', 'light' and 'top'.
    • In case of define blush:
      • type:type of blush to apply. Available types are: 'cShape', 'oval', 'square', 'triangle' and 'lift'.
    • In case of define mascara:
      • type:type of mascara to apply. Available types are: 'fake', 'false', 'volume' and 'length'.
    • In case of define concealer:
      • coverage: coverage of the concealer
    • In case of define bronzer:
      • type:type of bronzer to apply. Available types are: 'diamond', 'heart', 'long', 'oval', 'round', 'square'
      • coverage: coverage of the bronzer
      • finish:finish of the bronzer to apply. Available finishes are: 'matte', 'natural'
      • finishStrength: number between 0 and 1 that defines the strength of the finish.
    • In case of define highlighter:
      • coverage: coverage of the highlighter
    • In case of define foundation:
      • coverage: coverage of the foundation
    • In case of define eyebrows:
      • arc: % of the arc to transform. It can be a value between -1 and 1.
      • height: % of the height to transform. It can be a value between -1 and 1.

This is an example of an effects object:


  {
    lipstick: {
      enabled: true,
      color: [190, 6, 6],
      strength: 0.4,
      finish: 'gloss',
      finishStrength: 1,
    },
    lipliner: {
      enabled: true,
      color: [255, 20, 30],
      strength: 1,
      thickness: 1,
    },
    eyeliner: {
      enabled: false,
      color: [20, 20, 30],
      strength: 1,
      type: 'everyday',
    },
    blush: {
      enabled: false,
      color: [183, 10, 10],
      strength: 0.7,
      type: 'cShape'
    },
    eyeshadow: {
      enabled: true,
      color: [[143, 57, 102], [255, 255, 255],[0, 0, 0]],
      strength: 0.6,
      type: 'variant1',
      finish: 'metallic',
    },
    eyebrows: {
      enabled: true,
      color: [143, 57, 102],
      strength: 0.5,
      height: 0.3,
      arc: -0.3,
    },
    concealer: {
      enabled: false,
      color: [143, 57, 102],
      coverage: 0.35,
    },
    foundation: {
      enabled: false,
      color: [143, 57, 102],
      coverage: 0.1,
    },
    beautify: {
      enabled: false,
      strength: 0.8,
    },
    clipMask: {
      enabled: true,
      start: { x: 0, y: 0 },
      width: 200,
      height: 200,
    },
  }
          

Configuration for special effects:

  • beautify:
    • enabled: boolean flag to define if effect is enabled or don't.
    • strength: strength of the effect
  • clipMask:
    • enabled: boolean flag to define if effect is enabled or don't.
    • start: object that will define the x and y position of the top right point of the rectangle where the effect will be rendered.
    • width: width of the rectangle
    • height: height of the rectangle

Please take note that you don't need to define the whole object everytime you want to change the effects configuration. You just need to setup the values that you want to change. For example, if you want to disable the eyeshadow effect you will use this code:


  revieveSDK.liveAR.changeEffects({eyeshadow: {enabled: false}});
          

You can unmount the module using this code. It will release the webcam and destroy all DOM elements.


  revieveSDK.liveAR.release();
          

You can get a JPG image of the current liveAR effects with the method getImage.


  revieveSDK.liveAR.getImage();
          

Product Recommendations module (PR module)

Product recommendations module is used to filter the product catalog with the information stored in the SDK state object. You can change the state with all the set methods that are provided by the SDK core. These methods are:

  • revieveSDK.setSkintype(skintype): set skin type to filter. Skin types possible values can be taken from RevieveSDK.skinTypes property.
  • revieveSDK.setGender(gender): set gender to filter. Gender possible values can be taken from RevieveSDK.gender property.
  • revieveSDK.setHairColor(hairColor, requiredTag, variantName): set hair color to filter. Hair color possible values can be taken from RevieveSDK.hairColor property. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setEyeColor(eyeColor, requiredTag, variantName): set eye color to filter. Eye color possible values can be taken from RevieveSDK.eyeColor property. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setSkintoneColor(skintoneColor): set skintone color to filter.
  • revieveSDK.setCategories(categories): set categories to filter. Categories parameter must be a string array with the categories to include in query.
  • revieveSDK.setMatchToSkintoneCategories(categories): set the categories that will match the color skintone parameter (skintone_color_cv) during the product matching process.
  • revieveSDK.setAge(age): set age by setting the year of birth.
  • revieveSDK.setLat(lat): set the latitude of user's location. If left empty, API will automatically use latitude based on user IP address.
  • revieveSDK.setLon(lon): set the longitude of user's location. If left empty, API will automatically use longitude based on user IP address.
  • revieveSDK.setWrinkles(wrinkles): set how prominent wrinkles user has in their opinion between 0.0 - 1.0.
  • revieveSDK.setEyebags(eyebags): set how prominent eyebags user has in their opinion between 0.0 - 1.0.
  • revieveSDK.setDarkSpots(darkSpots): set how prominent darkSpots user has in their opinion between 0.0 - 1.0.
  • revieveSDK.setCuperose(cuperose, requiredTag, variantName): If the user has skin cornern "cuperose", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setRocasea(rocasea, requiredTag, variantName): If the user has skin cornern "rocasea", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setAcne(acne, requiredTag, variantName): If the user has skin cornern "acne", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setEczema(eczema, requiredTag, variantName): If the user has skin cornern "eczema", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setHyperpigmentation(Hyperpigmentation, requiredTag, variantName): If the user has skin cornern "Hyperpigmentation", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setOilyness(oilyness, requiredTag, variantName): If the user has skin cornern "oilyness skin", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setDullTired(dullTired, requiredTag, variantName): If the user has skin cornern "dull and tired skin", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setPsoriasis(psoriasis, requiredTag, variantName): If the user has skin cornern "psoriasis", set this to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setOrganic(organic, requiredTag, variantName): If user prefers organic products, set to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setAntiAge(antiAge, requiredTag, variantName): If user prefers antiaging products, set to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setFragranceFree(FragranceFree, requiredTag, variantName): If user prefers fragrance free products, set to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setParabenFree(parabenFree, requiredTag, variantName): If user prefers paraben free products, set to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setSunProtection(sunProtection, requiredTag, variantName): If user prefers sun protection products, set to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setSkinBrightening(skinBrightening, requiredTag, variantName): If user prefers skin brightening products, set to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setSkinFirming(skinFirming, requiredTag, variantName): If user prefers skin firming products, set to true. If you want to get ONLY products with this feature you can set requiredTag to true. If you want to make a variation with this filter, you can specify the variation name with variantName parameter.
  • revieveSDK.setLocale(locale)To set the chosen locale of the end user.

You can reset the filters setted by the previous methods calling revieveSDK.clearUIConfiguration().

There are some filtering capabilities that depends on the provider's product information. You can add a custom attribute to filter products based of this information with this code:


  revieveSDK.setCustomAttribute(customAttribute, value, requiredTag, variantName);
          

Please note that in all the cases requiredTag and variantName parameters are optional.

Variations: A variation can be seen as a grouping option in the query. For example, if I want to get to groups of products, one for day look and oher for night look, that is defined with two tags 'makeup_day' and 'makeup_night'. I can set this groups with this code:


  revieveSDK.setCustomAttribute('makeup_day', 1, true, 'day');
  revieveSDK.setCustomAttribute('makeup_night', 1, true, 'night');
            

After that, only the products with the 'makeup_day' tag will be present in the 'day' group, and the ones with 'makeup_night' in the 'night' group.

After you've modified the state to match the user needs with above methods, you can get a JSON list of recommended products in base of all the information set by methods above with this code:


  revieveSDK.PR.getRecommendedProducts()
  .then(()=>{
    ...
  })
  .catch(()=> {
    ...
  });
          

Please note that all apply effect methods are asynchronous and return a promises.

In case you have specifed variations (with variantName parameter), you will get an array with each variation defined that contains the products that match with the specific query criteria specified to the variation.

You can get the history id related with your query with revieveSDK.PR.getHistoryId() method. It would be helpful to track results.

You can get the individual product information with revieveSDK.PR.getProduct method. This method will return a promise. Once resolved, it will return a JSON object with the product information. If no product information is found with the given id then it will return null.


  revieveSDK.PR.getProduct('XXXXXXXXX')
  .then((productInfo)=>{
    ...
  })
  .catch(()=> {
    ...
  });
          

You can send data about products added to cart (for report and analytics purposes) with revieveSDK.PR.addToCart method. This method will return a promise. If resolved, data and analytics event would have been dispatched correctly.


  revieveSDK.PR.addTocart([{id:'XXX',price:10},{id:'YYY',price:20}])
  .then(()=>{
    ...
  })
  .catch(()=> {
    ...
  });
          

Analytics module

You can track the user interactions with the SDK with the analytics module. Currently, only Google Analytics trackers are available. Please note that you can add various trackers, for example, if you want to add various GA accounts where register the events. If you want to add a tracker you can use this code:


  revieveSDK.analytics.addTrackers([{provider: 'ga', prefix: 'revieveSDK', account: 'UA-XXXXXXXX-X'}]);
            

When you add a tracker, analytics module will send automatically all the methods registered in the SDK to all the trackers added.

The addTrackers module accepts an array as parameter. Each element of this array must be a JSON with this information:

  • provider: tracker's provider code. You can get the list of available providers in the SDK with the static property RevieveSDK.analyticsProvidersAvailable
  • prefix: prefix to be added to all the action registered in trackers
  • account: trackers account information

In case of Google Analytics trackers, you can add custom dimensions and metrics to the events sent by SDK. You can use this methods:

  • setCustomDimensionToGaTracker: method to add a custom dimension to a GA tracker. Parameters:
    • trackerIndex: Tracker's index where you want to add the custom metric
    • dimensionIndex: index of your custom dimention in your GA configuration
    • value: value to the custom dimension
  • setCustomMetricToGaTracker: method to add a custom metric to a GA tracker. Parameters:
    • trackerIndex: Tracker's index where you want to add the custom metric
    • metricIndex: index of your custom metric in your GA configuration
    • value: value to the custom dimension

Analytics can be disabled in case you don't want to use any telemetry. Please refer to the initializing section for more details