Sending events to Laudspeaker

A tutorial for sending your first events to Laudspeaker

Laudspeaker Event Structure

Laudspeaker supports the ingestion of events, and can ingest at a high throughput. Our endpoint https://app.laudspeaker.com/api/events/batch/ accepts events in batches. From as little as one event in a batch. Lets start off with an example you can run and then explain what is happening:

You can adapt the following curl example, by adding your api key (found in settings)

curl --location 'https://app.laudspeaker.com/api/events/batch/' \
--header 'Authorization: Api-Key [your_key_here]' \
--header 'Content-Type: application/json' \
--data '{
    "batch": [
    {
      "timestamp": "2024-03-15T02:31:05.295Z",
      "uuid": "F451DF0A-D713-4076-AE20-41AB1641BC98",
      "event": "purchase",
      "source": "mobile",
      "correlationKey": "_id",
      "payload": {
        "cart": true
      },
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5"
    },
    {
      "timestamp": "2024-03-15T02:31:05.313Z",
      "uuid": "A97E8A44-AAB0-45C6-B68D-3CAD9A0ED0DD",
      "correlationKey": "_id",
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5",
      "source": "mobile",
      "event": "agree_to_marketing",
      "payload": {
        "agreement": true
      }
    },
    {
      "correlationKey": "_id",
      "source": "mobile",
      "uuid": "24291D14-944D-4C7B-B0E4-EC98B8A9DF46",
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5",
      "event": "onboarding_started",
      "payload": {
        "service": "something",
        "campaign": "utm-1234",
        "tap": "open"
      },
      "timestamp": "2024-03-15T02:31:05.333Z"
    },
    {
      "source": "mobile",
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5",
      "event": "onboarding_started",
      "correlationKey": "_id",
      "uuid": "46300C36-EB75-483D-9955-555233CE648C",
      "payload": {
        "service": "MY",
        "user": "utm-234",
        "tap": "main"
      },
      "timestamp": "2024-03-15T02:31:05.353Z"
    },
    {
      "source": "mobile",
      "correlationKey": "_id",
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5",
      "payload": {
        "id": 2,
        "service": "MY"
      },
      "timestamp": "2024-03-15T02:31:05.443Z",
      "uuid": "C3EE7322-CBA2-49C4-B118-87DD86AAA5D0",
      "event": "item_to_cart"
    }
  ]
}'

and you should see the resulting events in the event tracker!

Breaking down the batch of events

A batch consists of an array of events and looks like this:

{
    "batch": [
    {
      "timestamp": "2024-03-15T02:31:05.295Z",
      "uuid": "F451DF0A-D713-4076-AE20-41AB1641BC98",
      "event": "checking_out",
      "source": "custom"
      "correlationKey": "_id",
      "payload": {
        "checkout": true
      },
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5"
    }
  ]
}

Each event in the batch must adhere to the laudspeaker schema, at a minimum each event must contain an event field, correlationKey field, correlationValue field, and a source set to “custom”

Optionally it should also contain a timestamp, and uuid like below:

    {
      "timestamp": "2024-03-15T02:31:05.295Z",
      "uuid": "F451DF0A-D713-4076-AE20-41AB1641BC98",
      "event": "checking_out",
      "source": "custom"
      "correlationKey": "_id",
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5"
    }

To customize your event with data you want to send, you should include a payload object:

    {
      "timestamp": "2024-03-15T02:31:05.295Z",
      "uuid": "F451DF0A-D713-4076-AE20-41AB1641BC98",
      "event": "checking_out",
      "source": "custom"
      "payload": {
        "checkout": true
      },
      "correlationKey": "_id",
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5"
    }

Putting everything together an event batch could look like:

{
    "batch": [
    {
      "timestamp": "2024-03-15T02:31:05.295Z",
      "uuid": "F451DF0A-D713-4076-AE20-41AB1641BC98",
      "event": "checking_out",
      "source": "mobile"
      "correlationKey": "_id",
      "payload": {
        "checkout": true
      },
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5"
    },
    {
      "timestamp": "2024-03-15T02:31:05.313Z",
      "uuid": "A97E8A44-AAB0-45C6-B68D-3CAD9A0ED0DD",
      "correlationKey": "_id",
      "correlationValue": "FBBBCB26-B75E-4342-B40B-568BF879F7C5",
      "source": "mobile",
      "event": "marketing_agreed",
      "payload": {
        "agreed_to_marketing": true
      }
    },
  ]
}

API Endpoint

Our event endpoint is:

https://app.laudspeaker.com/api/events/batch/

Identifying users

We are able to attribute events to the right users by using the correlationValue and correlationKey pair. The correlationKey tells Laudspeaker which unique attribute of a user to use when correlating an event with a user, and for custom events should always be set to the primary key of the user. The primary key of your users is set up under the audience tab: