Client Side SDK Quick Links

Client Side SDK

The client SDK is a JavaScript library that has to be included in your app. 

We provide an API that lets you save information about your app users. API calls need to go through your own server. This is necessary because of the use of secret keys for validating, reading and generating JSON Web Tokens. You can use our server SDK to do API calls to our server and to validate, read and generate JSON Web Tokens. For more information and examples, have a look at the Server part of the SDK documentation.

Contacts

Builder.postContact(url, contact, onSuccess, onError)

Posts a contact. You can also use this function to include more (not change) data to an existing contact. When a new user is created, the SDK will create a cookie with the user id. When a user revisits the website, it will be automatically added to any postContact call.

Parameters

Name Type Description
url String The endpoint of your server that handles the posting a contact.
contact Object The contact object. (see example)
onSuccess Function On success callback function.
onError Function On error callback function.

Example

Builder.postContact() example

const url = 'https://yourserver.com/api/contacts/post'

// Structure of a contact object
const contact = {
            'Name': {
                'Last': 'Doe',
                'First': 'John'
            },
            'Birthdate': 0,
            'PictureUrl': '',
            'Company': '',
            'Email': {
                'Email': 'johndoe@web.com'
            },
            'Address': {
                'Address': '',
                'Address2': '',
                'City': '',
                'State': '',
                'Country': '',
                'PostalCode': ''
            },
            'DeliveryAddress': {
                'Address': '',
                'Address2': '',
                'City': '',
                'State': '',
                'Country': '',
                'PostalCode': ''
            },
            'Phone': ''
        }

const onSuccess = (response) => {
  console.log(response)
}

const onError = (response) => {
  console.log(response)
}

Builder.postContact(url, contact, onSuccess, onError)

Builder.getContacts(url, scope, offset, limit, onSuccess, onError)

Gets contacts.

Parameters

Name Type Description
url String The endpoint of your server that handles getting contacts.
scope String The scope of the contacts. This can be ‘app’ or ‘site’.
offset String Set an offset for the contacts to get.
limit Number Limit the number of contacts to get.
onSuccess Function On success callback function.
onError Function On error callback function.

Example

Builder.getContacts() example

const url = 'https://yourserver.com/api/contacts/get'

const scope = 'app'

const offset = '0'

const limit = 50

const onSuccess = (reponse) => {
  console.log(response)
}

const onError = (response) => {
  console.log(response)
}


Builder.getContacts(url, scope, offset, limit, onSuccess, onError)

Events

Builder.postEvent(url, event, onSuccess, onError)

Post an event.

Parameters

Name Type Description
url String The endpoint of your server that handles posting an event.
event Object The event object. (see example)
onSuccess Function On success callback function.
onError Function On error callback function.

Example

Builder.postEvent() example

const url = 'https://yourserver.com/api/events/post'

const event = {
  'event_type': 'store_purchase',
  // The content can be anything, as long as it is an object
  'content': {
    'store_id': 'appmachine',
    'card_id': '09102017133515',
    'order_number': '61017114657'
  }
}

const onSuccess = (response) => {
  console.log(response)
}

const onError = (response) => {
  console.log(response)
}

Builder.postEvent(url, event, onSuccess, onError)

Builder.getEvents(url, since, until, contactId, scope, eventTypes, offset, limit, onSuccess, onError)

Get events.

Parameters

Name Type Description
url String The endpoint of your server that handles getting events.
since Number Unix timestamp to get events since a certain date/time.
until Number Unix timestamp to get events until a certain date/time.
contactId String A contact id. (can be an empty String)
scope String The scope of the event. This can be ‘app’ or ‘site’.
eventTypes String Comma separated string of event types to filter. (can be an empty String)
offset String An offset for the events to get.
limit Number Limit the number of events to get.
onSuccess Function On success callback function.
onError Function On error callback function.

Example

Builder.getEvents() example

const url = 'https://yourserver.com/api/contacts/get'

const since = new Date(2017, 6, 6).getTime()

const until = new Date().getTime()

const contactId = '123e4567-e89b-12d3-a456-426655440000'

const scope = 'app'

const eventTypes = 'new_order,new_contact'

const offset = '0'

const limit = 50

const onSuccess = (response) => {
  console.log(response)
}

const onError = (response) => {
  console.log(response)
}


Builder.getEvents(url, since, until, contactId, scope, eventTypes, offset, limit, onSuccess, onError)

Messages

It is possible to communicate between multiple app components on a page.

Builder.Messages.subscribe(type, callback)

Subscribe to receiving messages of the specified type.

Parameters

Name Type Description
type String The message type you want to subscribe to.
callback Function A function that handles receiving messages of the specified type.

Example

Builder.Messages.subscribe()

const callback = (message) => {
    console.log(message)
}


Builder.Messages.subscribe('test_type', callback)

Builder.Messages.send(type, message)

Send a message to all app components on a page.

Parameters

Name Type Description
type String The message type.
message * The message, which can be a String, Object, Number or Boolean.

Example

Builder.Messages.send() example

const message = 'This is a message from another component'


Builder.Messages.send('test_type', message)

Builder.Messages.unsubscribe(type)

Unsubscribe from receiving message of the specified type.

Parameters

Name Type Description
type String The message type you want to unsubscribe from.

Example

Builder.Messages.unsubscribe()

Builder.Messages.unsubscribe('test_type')

App Properties

App component properties that you have set in the Developer Portal can be retrieved through the SDK.

Builder.getProperties()

Returns an object with all the properties of your app component. This method can be called after the componentLoaded event has been fired.

NOTE: The provided realtime updates of property changes in the Sitebuilder editor, you have to use this method instead of Builder.getPropertyValue().

Example

Builder.getProperties() example

// Function that will be executed when the 'componentLoaded' event has fired
const initialize = () => {
    const properties = Builder.getProperties()
}

// Before we can use this method, we have to be sure everything has loaded, so we listen to the 'componentLoaded' event.
document.addEventListener('componentLoaded', initialize)

Properties object example

{
  property1: "value1",
  property2: "value2"
}

Builder.getPropertyValueByName(name)

Returns the value of a property. Because this value is provided in the query string, you can call this function without having to wait for the ‘componentLoaded’ event.

Parameters

Name Type Description
name String The name of the property.

Example

Builder.getPropertyByName() example

const propertyValue = Builder.getPropertyValueByName("prop1")

Styles

We think it is important that the integration of the app in the website should be as good as possible. To help with this we provide a method to get information about the styling of the website like colors and fonts. Your app should implement that styling.

Builder.getStyles()

Return an object with the site colors and font.

Example

Builder.getStyles() example

// Function that will be called when the 'componentLoaded' event is fired
const initialize = () => {
  // Call the SDK function
  const styles = Builder.getStyles()

  // Change the colors of the app
  document.body.style.fontFamily = styles.font.fontFamily
  document.body.style.fontSize = styles.font.fontSize
  document.body.style.background = styles.colors.background
}
// Before we can use the SDK, we have to be sure everything has loaded, so we listen to the 'componentLoaded' event.
document.addEventListener('componentLoaded', initialize)

Styles object example

{
  'colors': {
    'text': '#ffffff',
    'background': '#000000'
  }
  'font': {
    'fontFamily': 'Lato',
    'fontSize': '15px'
  }
}

NOTE: The required font will be loaded automatically from our server. So you can safely set the font-family from the styles object.