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
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.
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.
First, we can pull out the hardcoded values so they can be personalized. The Resonance VS Code plugin can help with this process.
It may be helpful, though not necessary, to create a TypeScript interface for these CTA values.
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.
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.
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.
| Argument | Type | Description |
|---|---|---|
amplifierStoreUrl | String | The base URL for your instance of Amplifier Store |
options | ResonanceOptions | See the table below |
ResonanceOptions
| Property | Type | Description |
|---|---|---|
| clientId | string | Your client ID, found in the Resonance Portal under Developer Settings |
| apiKey | string | Your 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.
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.
Instance properties
| Property | Type | Description |
|---|---|---|
amplifierStoreUrl | string | The value of the amplifierStoreUrl passed into the constructor |
Instance methods
| Method | Description |
|---|---|
initGA | See description below |
| loadCustomization | This 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.
| arg | type |
|---|---|
| trackingId | string |
| APISecret | string |
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
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.
| arg | type |
|---|---|
| apiKey | string |
apiKey
This is your StatSig API key, which can be found in the StatSig portal. We recommend storing this key as a secret.
Usage
loadCustomization
The loadCustomization method takes a single options argument with the following properties
| Property | Type | Description |
|---|---|---|
| customizationType | string | The type of experience you are loading |
| surfaceId | string | The surface ID of the experience you are loading |
| userData | Record<string, unknown> | An object containing user data about the current user. This object should contain an `id` field. Other fields are optional. |
| defaultValue | unknown | The 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.