Events API

Bluecore’s events API can be used to capture data from your mobile app or other sources, in the same way that our JavaScript integration captures data from your website. You may POST various events to identify/update customers as well as record commerce events/behaviors, including custom events.

Endpoint

$ POST https://api.bluecore.app/api/track/mobile/v1
As of March 2024, the endpoint for API calls changed from api.bluecore.com to api.bluecore.app. Pre-existing integrations do NOT require any action as their URLs will be automatically re-routed to new endpoint. New integrations must be configured with the .app endpoint address.

Parameters


Types of calls

Capturing commerce events and behaviors

You may make calls to represent these standard events/behaviors:

  • viewed_product
  • search (used for keyword searches as well as category browse)
  • add_to_cart
  • remove_from_cart
  • wishlist
  • purchase
To update your product catalog, please reach out to your CSM.

Example - a product view event

{
    "event": "viewed_product",
    "properties": {
        "products": [
            {"id": "1234"}
        ],
        "distinct_id": "xyz@example.com",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad"
    }
} 

Example - a search event

{
    "event": "search",
    "properties": {
        "search_term": "logo design",
        "distinct_id": "xyz@example.com",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad"
    }
} 

Example - an add to cart event

{
    "event": "add_to_cart",
    "properties": {
        "products": [
            {"id": "1234"}
        ],
        "distinct_id": "1424532133a16a-07943fba1-1960426e-2c600-1424532133c98",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad"
    }
}  

Example - a remove from cart event

{
    "event": "remove_from_cart",
    "properties": {
        "products": [
            {"id": "1234"},
            {"id": "5678"}
        ],
        "distinct_id": "1424532133a16a-07943fba1-1960426e-2c600-1424532133c98",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad"
    }
} 

Example - a purchase event

{
   "event": "purchase",
   "properties": {
       "products": [
           {"id": "1234"},
           {"id": "5678"}
       ],
       "total": 400.20,
       "order_id": "ABCDE12345",
       "distinct_id": "xyz@example.com",
       "token": "bluestore",
       "client": "4.0",
       "device": "mobile/iPad",
       "customer": {
           "email": "xyz@example.com"
       }
   } 
}

Example - an add to wishlist event

{
    "event": "wishlist",
    "properties": {
        "products": [
            {"id": "1234"}
        ],
        "distinct_id": "1424532133a16a-07943fba1-1960426e-2c600-1424532133c98",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad"
    }
} 

Creating and updating customers

You may make calls to create a new customer with optional attributes, or update attribute values for an existing customer.

Example - creating / updating a customer with attributes

{ 
     "event": "customer_patch", 
     "properties": { 
          "customer": { 
               "first_name": "X", 
               "last_name": "Yz" 
          }, 
          "distinct_id": "1424532133a16a-07943fba1-1960426e-2c600-1424532133c98", 
          "token": "bluestore" 
     } 
}
All customer attributes must be lowercase.
Customer attributes can't include a space or dash (-). Instead, they should use an underscore (_).
If using boolean attributes, they must use boolean values. For example:"boolean_attribute": true

Linking identifiers to emails

Across call types, the distinct_id parameter represents a unique customer identifier. This can be an email address when it is available, a customer ID in your database, a device id, or UUID that you generate and consistently use for the browsing customer.

IMPORTANT: For each new non-email distinct_id that you use for a customer, you must fire an “identify” event to link this identifier to the customer email address. This enables you to tie together all of a customer’s behaviors for a holistic view. Note this means you can capture behaviors for a customer prior to knowing their email, and have those behaviors intact and linked once you do obtain the email address (e.g. upon login or registration).

Example - linking a device ID with an email address

{
    "event": "identify",
    "properties": {
        "distinct_id": "1424532133a16a-07943fba1-1960426e-2c600-1424532133c98",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad",
        "customer": {
            "email": "xyz@example.com"
        }
    }
} 

Opting in and unsubscribing customers

You may make calls to opt-in or unsubscribe an email address.

Example - opting-in a customer email

{
    "event": "optin",
    "properties": {
        "distinct_id": "xyz@example.com",
        "email": "xyz@example.com",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad"
    }
} 

Example - unsubscribing a customer email

{
    "event": "unsubscribe",
    "properties": {
        "distinct_id": "xyz@example.com",
        "email": "xyz@example.com",
        "token": "bluestore",
        "client": "4.0",
        "device": "mobile/iPad"
    }
}

Server response

At this time, all calls will result in a 202 response (we are updating this!); please see Testing and QA for further guidance.

Testing and QA

The best way to test your calls to the Events API is to create example calls with example customers, and leverage our Audience Builder to verify successful capture. (Bluecore does not have traditional QA or dev environments). You may also send your test calls that you have made to Product Support (support@bluecore.com) and ask them to verify successful capture. Please ask your Customer Success Manager for more detail as needed.


Differentiating mobile events

Within Audience Builder, events that are captured via these API calls are differentiable from events captured via the JS integration or file feeds, using the is_mobile attribute.



Custom events

Generally, Bluecore can create custom events (e.g. sweepstakes_signup) that can be captured via any of your incoming data sources (website, mobile app, feeds, etc.) Please speak with your CSM about any desired custom events.