Node.js SDK

The Node.js SDK is intended to be used Node.js environments and not client-side (i.e. browser) environments, to avoid publicly exposing sensitive API secrets.

Installation

bash

Usage

Create an instance of resonance and set up analytics. It can be helpful to create a singleton instance that can be used anywhere in your app.

typescript

Loading personalization data

For each personalized experience in your app, you will load personalization data from Resonance. Example code is available with the Resonance portal for each experience type, so this code is for demonstration purposes only.

Personalized CTA example

Let’s say you have a CTA that you would like to personalize.

jsx

First, we can pull out the hardcoded values so they can be personalized. The Resonance VS Code plugin can help with this process.

jsx

It may be helpful, though not necessary, to create a TypeScript interface for these CTA values.

typescript

In the Resonance Portal, you will create an experience type with these values, as well as a surface. Here again, the VS Code plugin can help with this process. Just highlight the interface, open the command palette, and select “Resonance: Create experience type”. You can also fill these fields in yourself in the Resonance portal.

In your application server, you will use the Resonance SDK to load the CTA values. You can pass in a set of default values, in case there are no published experiences for a given user.

typescript

The value of cta can be used for server-side rendering, or sent to a web or mobile front-end to be rendered. In our example, our CTA code is ready to render these values.

jsx

Node SDK API

Below you will find detailed documentation on @resonance-run/resonance-node package.

Resonance class

The default export of the @resonance-run/resonance-node package is the Resonance class.

ArgumentTypeDescription
amplifierStoreUrlString
The base URL for your instance of Amplifier Store
optionsResonanceOptionsSee the table below

ResonanceOptions

PropertyTypeDescription
clientIdstringYour client ID, found in the Resonance Portal under Developer Settings
apiKeystringYour API key, generated in the Resonance Portal under Developer Settings

Instantiate without options

If you have deployed your own instance of Amplifier Store, you will only need to provide the URL for your instance, which should probably be set on an environment variable.

typescript

Instantiate with options

If you are using the Resonance-hosted Amplifier Store, you will need to instantiate with your API credentials in the options object. These credentials should be stored as environment secrets.

typescript
Instance properties
PropertyTypeDescription
amplifierStoreUrlstringThe value of the amplifierStoreUrl passed into the constructor
Instance methods
MethodDescription
initGASee description below
loadCustomizationThis method loads a customization for a given user, for a particular customization type and surface ID from Amplifier Store. A default value can be supplied, which will be returned if there is no customization for the given user. This default value is the control value.
initGA

This method initializes a connection with your Google Analytics, which allows Resonance to emit tracking events for when a user sees a particular variation of an experience or control. If you use Google Analytics, this method is required for proper A/B test analytics.

This method only needs to be run once, at the time when you create your Resonance instance. However, the method is idempotent, so it can be run as many times as you would like. Any experiences served before this method is called will not be tracked.

argtype
trackingIdstring
APISecretstring
trackingId

This is your Google Analytics Tracking ID, which can be found in the Google Analytics Admin dashboard.

APISecret

This is your Google Analytics API Secret, which can be found in the Google Analytics Admin dashboard.

Usage
typescript
initStatSig

This method initializes a connection with StatSig, which allows Resonance to emit tracking events for when a user sees a particular variation of an experience or control. If you use StatSig, this method is required for proper A/B test analytics.

The only needs to be run once, at the time when you create your Resonance instance. However, the method is idempotent, so it can be run at any time you would like.

argtype
apiKeystring
apiKey

This is your StatSig API key, which can be found in the StatSig portal. We recommend storing this key as a secret.

Usage
typescript
loadCustomization

The loadCustomization method takes a single options argument with the following properties

PropertyTypeDescription
customizationTypestringThe type of experience you are loading
surfaceIdstringThe surface ID of the experience you are loading
userDataRecord<string, unknown>An object containing user data about the current user. This object should contain an `id` field. Other fields are optional.
defaultValueunknownThe optional default value field should contain the default value of the experience for which you are loading the customization. If the default value is an object, Resonance will merge the customization with the default value, with customization value fields taking precedence over default value fields.
customizationType: string

The customization type of the customizations you are fetching. This is the ID chosen when the customization type was created. It is displayed on the customization detail page.

surfaceId: string

The surface ID of the customizations you are fetching. This ID is displayed on the customization detail page.

userData: Record<string, unknown>

An object of user data to be used to determine what customization (if any) to return. It is expected that this user data has an id property. Other properties are optional. The ID property is used both to decide if the user belongs in the control or variations buckets, and can also be used as the key to look up additional user profile data from the profile store.

defaultValue: K

You can optionally pass in a default value for the customization. This default value is expected to be of the same type as the customization data (K). The default value will be merged with the customization data and returned. This means that the default values will be used for any values that are not present in the customization data object.

Example loadCustomization usage
typescript