General information

Requirements

Frontend SDK is a data transfer method that must be activated for your SALESmanago account before you can start transferring Contact data, Key Information, and External Events to your SALESmanago database. Following the activation, you can whitelist a domain to get access to the Frontend SDK. You can only whitelist domains with the SALESmanago Monitoring Script present. The SDK can be used with the Google Tag Manager (GTM) or can be directly included as a JavaScript integration.

Technology

The Frontend SDK uses JavaScript to transfer Contact data and Key Information directly from the Contact’s browser via GET requests. This method for transferring data to SALESmanago is an alternative to the REST API (API v2 and API v3) designed primarily for integrating websites that cannot have their backend modified. The SDK developed by SALESmanago works even with browsers that restrict cross-domain requests and divides GET requests into packages to meet the 4096 URL limit for the GET method.

Note: While transferring External Events is possible via client-side JavaScript, it uses a different method to build the requests. For more information, see External Event transfer >>

Security

The technology used to transfer data (i.e., JavaScript) is a client-side technology, and as such, it is prone to manipulation by the end user. SALESmanago allows you to take a number of measures to minimize any potential risks:

• Allowed scopes—define the data types (scopes) that will be accepted by SALESmanago. For example, you can limit the Frontend SDK to allow only the assigning and removing of tags, and thus prevent any end-user who might have malicious intents from modifying Contact data.
• Limiting—Frontend SDK uses advanced request limiting for each of your domains to reduce the risk of bots interfering with your Contact database. Three limiting ranges are applied: per minute, per hour, and per day.
• Contact creation/update scope—decide whether the Frontend SDK should allow the creation and updating of Contact data or only the creation of new Contacts.
• Requiring subscription confirmation (optional)—decide whether Contacts opting-in for your newsletter should be required to confirm their subscription by clicking a link in an email.
• REST API—The Frontend SDK can be used in combination with the backend REST API that can handle the transfer of the most critical data.

Validations

To make sure the data transferred to SALESmanago is well-structured, ordered, and easily accessible, we use validations for specific fields. The most important validations include:

Compatibility

The Frontend SDK is compatible with all major browsers and operating systems.

Supported browsers:

• Google Chrome
• Mozilla Firefox
• Apple Safari
• Microsoft Edge
• Opera
• Other browsers supporting cross-domain GET requests

Supported operating systems:

• Windows
• MacOS
• Android
• iOS
• Linux
• Other operating systems without misconfigured firewall

Frontend SDK methods

Simple example:

    SMApi.set('email', 'name@example.com');
    SMApi.set('name', 'John Doe');
    SMApi.execute('contact');

Advanced example:

    const Contact = {};
    Contact.email = 'name@example.com';
    Contact.name = 'John Doe';
    Contact.addTags = ['CAT_FOOD'];
    SMApi.setDebugMode(true);
    SMApi.setAll(Contact);
    SMApi.execute('contact').then((result) => {
        console.log(result);
    });

The SALESmanago Frontend SDK offers a number of methods for managing the transfer of data. You can set a single data field or a number of fields at once, get the data that was previously set, clear the data, and transfer contact and/or keyInformation objects to SALESmanago. You can also enter a debug mode to get more information about the SDK during the development.

Methods:

Contact transfer

Sample request:

    const ContactData = {
        email: "name@example.com",
        name: "John Doe",
        phone: "+15554443322",
        externalId: "U12345",
        company: "Acme Inc.",
        state: "PROSPECT",
        birthday: "19870605",
        streetAddress: "Main Street 21",
        city: "San José",
        zipCode: "90210",
        province: "California",
        country: "US",
        addTags: ["T_SHIRTS", "SWEATERS", "UPSELL"],
        removeTags: ["FIRST_PURCHASE"],
        emailOptIn: 1,
        mobileOptIn: 0,
        monitoringOptIn: 1,
        consents: [{
            name: "TERMS_OF_SERVICE",
            status: 1
        }],
        standardDetails: {
            t_shirt_size: "XL",
            gender: "Male"
        },
        numberDetails: {
            shoe_size: 10
        },
        dateDetails: {
            member_since: "1459938888"
        }
    };

    SMApi.setAll(ContactData);
    SMApi.execute('contact').then((result) => {
        console.log(result);
    });

Sample response:

When executed, the Frontend SDK returns a promise. A resolved promise contains the following response:
{
    "requestId": "a1b2-...-c3d4",
    "contactId": "1234-...-cdef",
    "finalResponse": true
}

Additionally, an 'smclient' cookie is automatically set with the value of 'contactId'.

Contacts are the most important entities in SALESmanago. contact objects contain Contacts’ personal information, consents, and other details. For more information, see Contact upsert method >>

Key Information transfer

Sample request:

const KeyInformationData = {
    "email": "name@example.com",
    "keyInformation": {
        "numeric": [{
            "name": "Height",
            "value": 175
        }, {
            "name": "Weight",
            "value": 75.5
        }],
        "text": [{
            "name": "Favorite color",
            "value": "Blue"
        }, {
            "name": "Favorite food",
            "value": "Pizza"
        }]
    },
    "setAsNull": ["Pet owned"]
}

SMApi.setAll(KeyInformationData)
SMApi.execute('keyInformation');

Sample response:

When executed, the Frontend SDK returns a promise. A resolved promise contains the following response:
{
    "requestId": "a1b2-...-c3d4",
    "finalResponse": true
}

Key Information is a data type used to store zero- and first- party data in SALESmanago. Zero-party data is the most powerful data type in Marketing Automation because it is directly collected from the Contact, rather than being inferred or obtained from third parties. Use Key Information transfer to add or update data gathered on your website.

Fields:

External Event transfer

Simple example:

sm('extEvent', {
    "owner": "salesmanago.user@yourcompany.com",
    "email": "name@example.com",
    "date": 1659938888,
    "contactExtEventType": "DOWNLOAD"
});

Advanced example:

let date = new Date();
sm('extEvent', {
    "owner": "salesmanago.user@yourcompany.com",
    "email": "name@example.com",
    "date": date.getTime(),
    "contactExtEventType": "PURCHASE",
    "products": "p0123, p4567",
    "value": 189.99,
    "location": "examplecom",
    "products": "p0123, p4567",
    "externalId": "ID-123456",
    "details": ["detail1", "detail2"]
});

External Events represent the most important actions performed by Contacts, such as buying products (PURCHASE) or adding them to the cart (CART). You can use External Events to create Automation Processes, prepare transaction statistics, and feed product recommendation strategies.

Important: External Events are not transferred using the Frontend SDK and are transferred directly with a JavaScript function.

Important: An External Event can only be assigned to an existing Contact. If a Contact does not exist in SALESmanago, the Event will be discarded.

Fields:

External Event types

SALESmanago supports a number of External Event types. PURCHASE and CART Events are automatically included in the analytic panels. The other External Events are general-purpose types—you can use them to transfer any actions performed by Contacts.

Available External Event types:

• PURCHASE
• CART
• TRANSACTION
• CANCELLATION
• RETURN
• VISIT
• PHONE_CALL
• OTHER
• RESERVATION
• CANCELLED
• ACTIVATION
• MEETING
• OFFER
• DOWNLOAD
• LOGIN
• SURVEY

Product Collections

What are Product Collections?

Product Collections allow you to store information about products associated with individual Contacts. This data can later be used to target Contacts who have a specific product in a Collection or to synchronize Collection contents between different devices via Frontend SDK.

The most representative example is a Wishlist—when a Contact adds a product to their Wishlist, you can add it to the Wishlist Product Collection and later use the selector: Product Collection contains item(s) to select Contacts who took a liking to a specific product. Another example could be Interested in—a Product Collection for storing items a Contact has expressed interest in, for example, by hovering their cursor over a product or scrolling its description to a certain depth.

Product Collection types

There is no fixed list of Product Collection types. You can create a Product Collection using backend API v3 with any name you want. Some examples:

• Wishlist: A collection of products that a Contact has expressed interest in purchasing, and added them to a wishlist
• Interested in: A collection of products that a Contact has shown interest in, but have not added to their wishlist nor purchased.
• Purchased: A collection of products that a Contact has actually bought or ordered.
• Viewed: A collection of products that a Contact has viewed on an e-commerce platform or website.
• Favorites: A collection of products that a Contact has marked as their favorite for easy access.
• Recommended: A collection of products that are recommended to a Contact based on their previous interactions, purchase history, or browsing behavior.
• Reviewed: A collection of products that a Contact has reviewed or given feedback on.

Adding products to a Product Collection

Sample request:

let productCollectionData = {
    "collectionUUID": "0a1b-...-2c3d",
    "method": "add",
    "productIds": [
        "P0123",
        "P1234",
        "P2345"
    ]
};
SMApi.setAll(productCollectionData);
SMApi.execute('productCollection');

Sample request:

SMApi.set('collectionUUID', '0a1b-...-2c3d');
SMApi.set('productIds', ["P0123", "P1234", "P2345"]);
SMApi.set('method', "add");
SMApi.execute('productCollection');

You can add new products to a Product Collection using the following method:

Fields:

Sample response:

When t​his method is executed, the Frontend SDK returns a promise. A resolved promise will have the following form:
{
    "requestId": "a1b2-...-c3d4",
    "finalResponse": true
}

Removing products from a Product Collection

Sample request:

let productCollectionData = {
    "collectionUUID": "0a1b-...-2c3d",
    "method": "remove",
    "productIds": [
        "P0123",
        "P1234",
        "P2345"
    ]
};
SMApi.setAll(productCollectionData);
SMApi.execute('productCollection');

Sample request:

SMApi.set('collectionUUID', "0a1b-...-2c3d");
SMApi.set('productIds', ["P0123", "P1234", "P2345"]);
SMApi.set('method', "remove");
SMApi.execute('productCollection');

You can remove products from a Product Collection using the following method:

Sample request:

When t​his method is executed, the Frontend SDK returns a promise. A resolved promise will have the following form:
{
    "requestId": "a1b2-...-c3d4",
    "finalResponse": true
}

Live Chat Frontend API

Sample use: Open Live Chat window after 5 seconds on the website

window.addEventListener('message', function(event) {
    let json;


    try {
        json = JSON.parse(event.data);
    } catch {
        return null;
    }


    if (json.topic === 'LIVE_CHAT_API_STARTED') {
        this.setTimeout(() => {
            this.window.smLiveChat.open();
        }, 5000);
    }
})

Sample use: Close small widget on mobile

window.addEventListener('message', function(event) {
    let json;


    try {
        json = JSON.parse(event.data);
    } catch {
        return null;
    }


    if (json.topic === 'LIVE_CHAT_API_STARTED') {
        if (window.innerWidth <= 768) {
            smLiveChat.closeSmallWidget();
        }
    }
})

Live Chat is a one-to-one communication channel natively built into SALESmanago. Using actions, you can programmatically open and close the Live Chat window and check its current state. Using events, you can set a callback that will be executed whenever the subscribed action is performed.

Actions

Methods available for smLiveChat object:

Sample use: Add Google Analytics event on open

let liveChatEvent = function() {
    gtag('event', 'screen_view', {
        'module': 'SALESmanago Live Chat'
    });
}

window.addEventListener('message', function(event) {
    let json;


    try {
        json = JSON.parse(event.data);
    } catch {
        return null;
    }


    if (json.topic === 'LIVE_CHAT_API_STARTED') {
        smLiveChat.registerOnAfterOpen(liveChatEvent);
    }
})

Sample use: Confirm before closing the Live Chat window

let showConfirmation = function() {
    return confirm("Are you sure you want to close the Live Chat?");
}

window.addEventListener('message', function(event) {
    let json;


    try {
        json = JSON.parse(event.data);
    } catch {
        return null;
    }


    if (json.topic === 'LIVE_CHAT_API_STARTED') {
        smLiveChat.registerOnbeforeClose(showConfirmation);
    }
})

Events

Methods available for smLiveChat object:

Web Push Frontend API

Sample use (display consent prompt with specified ID):

window.addEventListener('message', (event) => {
  if (event.data) {
    const data = JSON.parse(event.data);

    if (data.topic === 'WEB_PUSH_API_STARTED') {
      smWebPushApi.displayConsentForm('08673fa0-dc17-40ac-8b90-5867ae8d5801');
    }
  }
});

Sample use (display consent prompt with specified ID on button click):

HTML:

<button class="consent__button">Subscribe to our notifications!</button>

JavaScript:

const button = document.querySelector('.consent__button');
button.style.display = 'none';

window.addEventListener('message', (event) => {
  if (event.data) {
    const data = JSON.parse(event.data);

    if (data.topic === 'WEB_PUSH_API_STARTED') {
      button.style.display = 'block';

      button.addEventListener('click', () => {
        smWebPushApi.displayConsentForm('08673fa0-dc17-40ac-8b90-5867ae8d5801');
      });
    }
  }
});

Web Push notifications are brief, browser-based messages that can be sent both to Contacts and anonymous visitors. The SALESmanago API offers functionalities for programmatically requesting consent to these notifications and retrieving consent statuses, ensuring adherence to user preferences and regulatory requirements.

Methods available for smWebPushApi object:

Visit monitoring Frontend API

Sample use: Register current page, with parameters, without anchor

const currentPathname = window.location.pathname;
sm.api.registerVisit(currentPathname, false, true);

Response: void

Website visit monitoring is built into the SALESmanago Monitoring Code. With this API, you can extend your visitor monitoring capabilities, transferring visit events directly with JavaScript, which can be especially useful for websites built as SPAs. You can also get visit and pageview data for the current visitor.

Register a monitored visit

Method: sm.api.registerVisit(pathname, skipParams, skipAnchor);

Response:
This method does not return a value (void).

Sample use:

sm.api.pageStats();

Sample response:

{
    "visits": 4,
        "views": 57,
        "ts": 1659938888000,
        "isNewSession": false
}

Get visit statistics

Method: sm.api.pageStats();

Response: