---
title: JS API
slug: js-api
description: Improve user experience with Personizely's JavaScript methods for flexible website customization. Identify and track visitors with the Identify API, Goals with the Goal Tracking API, and Events with the Custom Event Tracking API. Display widgets with the 
docTags: 
createdAt: 2021-11-18T12:46:26.000Z
---

Personizely exposes some JavaScript methods to give you more flexibility in using it.

# Identify API

`ply.identifyVisitor(data)`

This method returns a Promise.

**data** - *object*, containing information about the visitor and custom fields values. The object can have the following properties:

**email** - *string*, a valid email address
**firstName** - *string*, visitor's first name
**lastName** - *string*, visitor's last name
**phone** - *string*, visitor's phone number
**companyName** - *string*, visitor's company name
**companyTitle**- *string*, visitor's company title
**marketingConsent**- *boolean*, visitor's marketing consent status
**privacyConsent**- *boolean*, visitor's privacy consent status
**address** - *string*, visitor's address
**bio** - *string*, visitor's bio
**customFieldValues** - *object*, visitor's custom field's values

The **custom field values** object is an object where the keys are the custom fields id's which can be found on the Settings page and the values are the values of the respective fields for the current visitor.

For radio and select field types you need to make sure that the choice options are valid ones, so if you have a field named "Gender" with 2 options: Male, Female, you won't be able to save a different value than one of those two values.
The checkbox type fields should receive a boolean value.
The number type fields should receive a numeric value.

Example:

```javascript
ply.identifyVisitor({
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1665599555",
  "companyName": "Personizely",
  "companyTitle": "CEO",
  "marketingConsent": true,
  "privacyConsent": true,
  "address": "5th Avenue",
  "bio": "My bio",
  "customFieldValues": {
     "1": "Male"
   }
})
```

# Goal Tracking API

`ply.trackGoal(eventName, value)`

This method is used to track custom goals.

**eventName** - *string*, the name of the event (this should be the name of an existing goal in your Personizely website settings). 
**value** - *number*, goal value in the currency of your website

For example, to track a **purchase** worth **$100** on your site, you can use the following code on your thank-you page:
`ply.trackGoal('Purchase', 100)`

# Custom Event Tracking API

`ply.trackEvent(eventName, value)`

This method is used to track custom events.

**eventName** - *string*, the name of the event (this can be any arbitrary event name or the name of an existing goal in your Personizely). 
**value** - *number*, event value in the currency of your website (optional)

For example, to track an **add to cart** event worth **$29** on your site, you can use the following code when a visitor adds a product to the cart:
`ply.trackEvent('Add to cart', 29)`

# Widgets API

`ply.showWidget(id, suppressRules, stepId)`

This method is used to show up any widget regardless of the triggers it has assigned to it.

**id** - *integer*, the id of the widget
**suppressRules** - (optional) *boolean*, whether to suppress the widget rules
**stepId** - (optional) *int*, the id of the step to open the widget on. Use this if you need to skip a step or reopen the widget on a specific step.

# Campaigns API

`ply.runCampaign(id)`

This method is used to run a campaign manually.

**id** - *integer*, the id of the campaign

Returns - the displayed `variation` or null/undefined if the user falls into the control group.

For full-stack campaigns, you can retrieve the enabled features with:

`variation.getFeature(featureKey)`

**featureKey** - *string*, the key of the feature as defined when the feature is created

Returns the `feature`

To get a parameter of a feature, use this:

`feature.getParameterValue(key)`

**key** - *string*, the key of the parameter

Example:

:::BlockQuote
const variation = ply.runCampaign(3000000)
if (variation) \{
  const cartFeature = variation.getFeature('cart')
  if (cartFeature.isEnabled()) \{
     const message = cartFeature.getParameterValue('message')
     alert(message)
  }
} else \{
  // Control
}
:::

# Website Data API

This method is used to set website data. The method can be called in two ways:

**1st way**:

`ply.setData(data)`

**data** - *object, *an object containing key-value data pairs, the values will be merged with the existing data object.

**2nd way:**

`ply.setData(key, value)`

**key** - *string*, the name of the key to be written to the data object. 
**value** - *mixed, *the value, can be *string, boolean, number, null*

For example, to add cart details to your website data, you can use:
`ply.setData('cartSize', 5)` to set a single value or:

`ply.setData({cartSize: 5, cartValue: 99})` to set multiple values at once.

## Managing a situation where Personizely is not yet loaded

Personizely has a dataLayer-like solution to call the JS API even if the script is not yet loaded. To do that, use the following example:

```javascript
  window.plyLayer = window.plyLayer || []
  window.plyLayer.push(['trackEvent', 'purchase', 100])])
```