Generic Functions

Synchronous vs. Promise-Based Functions

Some functions return a value immediately, while others return a promise and must be awaited (or chained with .then()). If you use a promise-based function directly, you get back a Promise object instead of the value. Functions that return a value immediately:

_aimtellCheckPermissions()
_aimtellSupportsPush()
_aimtellPrompt()
_aimtellForcePrompt()

Functions that return a promise:

_aimtellGetSubscriberID()
_aimtellGetPushToken()
_aimtellGetSubscriberIDFromToken(token)
_aimtellGetSubscriberAttributes()
_aimtellGetNotifications()
_aimtellMarkNotificationsRead(timestamp)
_aimtellMarkNotificationsUnread(timestamp)
_aimtellDeleteNotifications(timestamp)

// Incorrect - logs a Promise object, not the subscriber id
console.log(_aimtellGetSubscriberID());

// Correct - with .then()
_aimtellGetSubscriberID().then(function(subscriberID){
  console.log(subscriberID);
});

// Correct - with async/await
async function logSubscriberID(){
  var subscriberID = await _aimtellGetSubscriberID();
  console.log(subscriberID);
}

Aimtell functions are only available once the script has finished loading. If you’re calling them on page load, do it from inside _aimtellReady().

Check Permissions

_aimtellCheckPermissions()

Description: Checks visitor’s push notification permissions Params: N/A Response: (str) - granted, default or denied

Example

console.log(_aimtellCheckPermissions()); // "granted", "default" or "denied"

Supports Push

_aimtellSupportsPush()

Description: Checks to see if visitor’s browser supports push notifications Params: N/A Response: (boolean)

Example

console.log(_aimtellSupportsPush()); // true or false

Get Subscriber ID

_aimtellGetSubscriberID()

Description: Grabs the active visitor’s subscriber id. If none exists, one is generated. Params: N/A Response: promise, (str) subscriber id

Example

_aimtellGetSubscriberID().then(function(subscriberID){
  console.log(subscriberID);
});

Example response:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

Get Push Token

_aimtellGetPushToken()

Description: Pulls the device push token from the current visitor. This is delivered as a javascript promise. Params: N/A Response: promise, (str) device token

Example

_aimtellGetPushToken().then(function(token){
  console.log(token);
});

Example response:

"cJ4h1Zq0TnE:APA91bGx7vN2mQd8sYk..."

Resolves to null if the visitor isn’t subscribed or the browser doesn’t support push.

Get Subscriber ID From Token

_aimtellGetSubscriberIDFromToken(token)

Description: Grabs visitors subscriber id based on push token Params:

token - required. browser push token

Response: promise, (obj) result, uid

Example

_aimtellGetSubscriberIDFromToken(token).then(function(result){
  console.log(result);
});

Example response:

{
  "result": "success",
  "uid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

If no subscriber matches the token:

{
  "result": "error",
  "message": "No subscriber found matching token."
}

Get Subscriber Attributes

_aimtellGetSubscriberAttributes()

Description: Grabs current website subscriber’s attributes. Params: N/A Response: promise, (obj) with idSite, subscriber_uid and custom_attributes. custom_attributes is an object of your tracked attribute name/value pairs, and is empty if none have been set.

Note: As custom attributes may contain information which an Aimtell website owner may not want easily viewable, this function by default is locked as a security measure. You must specifically request our team to unlock it for your account.

Example

_aimtellGetSubscriberAttributes().then(function(response){
  console.log(response);
});

Example response:

{
  "idSite": "20531",
  "subscriber_uid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "custom_attributes": {
    "age": "35",
    "name": "david"
  }
}

Show Push Prompt

_aimtellPrompt()

Description: If custom push prompt exists, show it, else load native push prompt Params: N/A Response: null

Example

_aimtellPrompt();

Force Push Prompt

_aimtellForcePrompt()

Description: Force shows the custom optin, even if previously denied. Params: N/A Response: null

“Previously denied” refers to the visitor dismissing your custom optin. If the visitor has already granted or denied permission at the browser level, this function does nothing. Browser permissions can only be changed by the visitor in their browser settings.

Example

_aimtellForcePrompt();

Get Notifications

_aimtellGetNotifications()

Description: Returns the subscriber’s notifications, most recent first. Params: N/A Response: promise, (array) of notification objects with the following fields:

title - notification title
body - notification body
icon - icon URL
link - destination URL
read - (boolean) true if read, false if unread
timestamp - used to target a single notification in the functions below

Example

_aimtellGetNotifications().then(function(notifications){
  console.log(notifications);
});

Example response:

[
  {
    "title": "Your order has shipped",
    "body": "Track your package for delivery updates.",
    "icon": "https://example.com/icon.png",
    "link": "https://example.com/orders/1234",
    "read": false,
    "timestamp": 1754838000
  },
  {
    "title": "Weekend sale starts now",
    "body": "20% off everything through Sunday.",
    "icon": "https://example.com/icon.png",
    "link": "https://example.com/sale",
    "read": true,
    "timestamp": 1754751600
  }
]

Returns an empty array if the subscriber has no notifications.

Mark Notifications Read

_aimtellMarkNotificationsRead(timestamp)

Description: Marks notifications as read. Pass a timestamp to mark a single notification, or call with no arguments to mark all notifications as read. Params:

timestamp - optional. The timestamp value from a _aimtellGetNotifications() response item. Pass it through unchanged.

Response: promise, (obj) { updated: <count> }

Example

// Mark all notifications as read
_aimtellMarkNotificationsRead().then(function(result){
  console.log(result); // { updated: 3 }
});

// Mark a single notification as read
_aimtellMarkNotificationsRead(1754838000).then(function(result){
  console.log(result); // { updated: 1 }
});

Mark Notifications Unread

_aimtellMarkNotificationsUnread(timestamp)

Description: Marks notifications as unread. Pass a timestamp to target one, or omit to mark all notifications as unread. Params:

timestamp - optional. The timestamp value from a _aimtellGetNotifications() response item. Pass it through unchanged.

Response: promise, (obj) { updated: <count> }

Example

// Mark all notifications as unread
_aimtellMarkNotificationsUnread().then(function(result){
  console.log(result); // { updated: 3 }
});

// Mark a single notification as unread
_aimtellMarkNotificationsUnread(1754838000).then(function(result){
  console.log(result); // { updated: 1 }
});

Delete Notifications

_aimtellDeleteNotifications(timestamp)

Description: Deletes notifications. Pass a timestamp to delete a single notification, or omit to delete all of the subscriber’s notifications. Params:

timestamp - optional. The timestamp value from a _aimtellGetNotifications() response item. Pass it through unchanged.

Response: promise, (obj) { deleted: <count> }

Example

// Delete all notifications
_aimtellDeleteNotifications().then(function(result){
  console.log(result); // { deleted: 3 }
});

// Delete a single notification
_aimtellDeleteNotifications(1754838000).then(function(result){
  console.log(result); // { deleted: 1 }
});

Javascript API

REST API

REST API - Push Notifications

REST API - Sites

REST API - Segmentation

REST API - Other

Generic Functions

Synchronous vs. Promise-Based Functions

Check Permissions

Example

Supports Push

Example

Get Subscriber ID

Example

Get Push Token

Example

Get Subscriber ID From Token

Example

Get Subscriber Attributes

Example

Show Push Prompt

Example

Force Push Prompt

Example

Get Notifications

Example

Mark Notifications Read

Example

Mark Notifications Unread

Example

Delete Notifications

Example

​Synchronous vs. Promise-Based Functions

​Check Permissions

​Example

​Supports Push

​Example

​Get Subscriber ID

​Example

​Get Push Token

​Example

​Get Subscriber ID From Token

​Example

​Get Subscriber Attributes

​Example

​Show Push Prompt

​Example

​Force Push Prompt

​Example

​Get Notifications

​Example

​Mark Notifications Read

​Example

​Mark Notifications Unread

​Example

​Delete Notifications

​Example

Synchronous vs. Promise-Based Functions

Check Permissions

Example

Supports Push

Example

Get Subscriber ID

Example

Get Push Token

Example

Get Subscriber ID From Token

Example

Get Subscriber Attributes

Example

Show Push Prompt

Example

Force Push Prompt

Example

Get Notifications

Example

Mark Notifications Read

Example

Mark Notifications Unread

Example

Delete Notifications

Example