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:
Data type | Standard | External resources |
---|---|---|
RFC882 | RFC882 at ietf.org | |
URL | Apache URL validator | UrlValidator at apache.org |
Currency | ISO 4217 | ISO 4217 at SIX |
Language | ISO 639-1 | ISO 639-1 at loc.gov |
Language and region | BCP 47 | BCP 47 codes at Microsoft |
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:
Method | Description |
---|---|
Initialization | No initialization is required. Once you activate the Frontend SDK for your domain, the SMApi object will be available through the Monitoring Script. |
SMApi.set(field, data) |
Allows you to set a field with data . Both arguments are required. |
SMApi.setAll(dataObject) |
Allows you to set a number of fields at once with a JSON dataObject . |
SMApi.get(field) or SMApi.get(null) |
Allows you to get a previously set field . If the field argument is missing, all previously set fields are retrieved. |
SMApi.clear(field) or SMApi.clear(null) |
Allows you to clear a previously set field . If the field argument is missing, all previously set fields are cleared. |
SMApi.execute('contact'); or SMApi.execute('keyInformation') |
Allows you to transfer contact and keyInformation objects. The method returns a promise that is resolved once the data transfer is complete. |
SMApi.setDebugMode(true) |
Allows you to enable the debugging mode to get additional information and statuses while setting and transferring data. |
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: "20220101"
}
};
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 >>
Note: Tags present in both the add and remove arrays will be removed only. In that event, Automation Processes based on assigning a tag or increasing a tag scoring will not be triggered.
- -1: Contact has rejected or withdrawn the consent
- 0: Contact has neither given nor rejected the consent. The status in SALESmanago will not change. If there was no status, the consent will be set as rejected
- 1: Contact has given the consent
(object)
emailOptIn
emailOptIn
.
Default value is 1 (Contact will be monitored).(array of objects)
- -1: Contact has rejected or withdrawn the consent
- 0: Contact has neither given nor rejected the consent. The status in SALESmanago will not change. If there was no status, the consent will be set as rejected
- 1: Contact has given the consent
(object)
Standard details can be used to store additional information about Contacts.
(object)
(object)
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:
Field | Limits | Description |
---|---|---|
email* | RFC882 | Contact identifier (email address or Contact ID) |
contactid* | UUID | Contact identifier (email address or Contact ID) |
keyInformation* (object) |
Object wrapping numeric and text arrays | |
numeric (array of objects) |
Array of numeric Key Information | |
text (array of objects) |
Array of text Key Information | |
name | 255 | Key Information name |
value | 255/BigDecimal | Key Information value |
setAsNull | 20x255 | Array of Key Information names to be nulled |
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:
Field | Limits | Description |
---|---|---|
owner* | 255 | Contact owner (SALESmanago user account email) |
email* | 254[?] | Email of Contact to whom the External Event is added |
contactId | UUID | Contact ID in SALESmanago; you will receive it in response to each request when adding or modifying a Contact. If you identify Contacts using contactId , the email field is optional. |
date* | timestamp | UNIX timestamp [s] |
contactExtEventType* | enum | External Event type, e.g., PURCHASE or CART |
products | 512 |
A comma-separated list of product IDs. Important: The product IDs sent in the Event should match the product IDs in your Product Catalog / XML Product Feed |
value | float (19.2) | Event value (e.g., purchase total) |
E-shop ID (location) | 36 |
Store identifier that matches the location field provided when creating the Product Catalog / XML Product Feed. It allows you to link an External Event to products from a specific store (or a specific language version of a store).
The location field can contain a maximum of 36 characters (only letters a-z, A-Z, numbers 0-9, and _ character). The value must not start with a number.
Tip: You can use the domain name without the dot, as in examplecom (or examplecom_ES for a specific language version of the store). |
externalId | 255 | Additional External Event identifier, e.g., order ID from your eCommerce platform |
detail1 | 20x255 |
External Event details that can be used in Automation Processes, in emails, or when exporting data via API. Examples of use: number of products purchased, value or category of the most expensive product, payment method, shipping method, packaging method |
detail2 | ||
detailX | ||
description | 2048 | A general-purpose field that can be used for order notes, an order summary link, a cart recovery link, etc. |
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