Developers

mParticle provides an HTTP-based Pixel Service that can be used to collect data using a simple GET request.

Authentication

This document assumes that you have already created a Web SDK Input. Please follow the instructions on our Web SDK Quickstart Guide to obtain a Web SDK API Key.

Sending data to Pixel Service

All requests to the pixel service must be made to the following url: https://pixels.mparticle.com/v1/{{web_api_key}}/Pixel, followed by URL Encoded Query Parameters for event attributes. For example:

https://pixels.mparticle.com/v1/{{web_api_key}}/Pixel?ct={{timestampMs}}&dbg=true&n=Custom%20Pixel%20Event&dt=AppEvent&et=Unknown

To send data to the Pixel service, you can make requests via any HTTP client using your Web API Key access credentials.

For the JS code sample, we will be using the Fetch API which is supported by most modern browsers.
You can also include 1x1 image pixel via HTML for cases where client side JavaScript is unavailable, such as for email tracking.

JavascriptHTML

async function sendPixel() {
    const pixelServiceURL = `https://pixels.mparticle.com/v1/${apiKey}/Pixel`;
    const currentTime = new Date().getTime();

    const eventName = "My Custom Event";
    const messageType: "AppEvent";
    const eventType: "Navigation";

    const queryParams = `n=${eventName}&dt=${messageType}&ct=${currentTime}&et={eventType}`;

    try {
        const response = await fetch(url + "?" + queryParams);
        if (!response.ok) {
            throw new Error(`Response status: ${response.status}`);
        }

        const json = await response.json();
        console.log(json);
    } catch (error) {
        console.error(error.message);
    }
}

<img
    height="1"
    width="1"
    style="display:none"
    src="https://pixels.mparticle.com/v1/{your-apikey-goes-here}/Pixel?n=My%20Page%20Viewdt=ScreenView&ct={current time stamp}&et=Navigation&dbg=true"
/>

Event Attributes

The following attributes must be submitted as URI query parameters:

Attribute	Name	Required	Description
`dt`	Event Type	yes	`AppEvent` for Custom Event or `ScreenView` for a Page View
`et`	Custom Event Type	no	The type of custom event based on our event list. Defaults to `Unknown`
`ct`	Current Time Timestamp	yes	Timestamp as Epoch (in milliseconds)
`n`	Event Name	no	Event Name as String
`attrs_k`	Event Attribute Keys	no	Comma Separated list of Custom Event Attribute Keys
`attrs_v`	Event Attribute Keys	no	Comma Separated list of Custom Event Attribute Values
`ua_k`	User Attribute Keys	no	Comma Separated list of User Attribute Keys
`ua_v`	User Attribute Values	no	Comma Separated list of User Attribute Values
`ui_t`	User Identity Type Keys	no	Comma Separated list of User Identity Keys
`ui_v`	User Identity Values	no	Comma Separated list of User Identity Values
`flags_k`	Custom Flag Keys	no	Comma Separated list of Custom Flag Values
`flags_v`	Custom Flag Values	no	Comma Separated list of Custom Flag Values
`lc`	Location	no	Format: `lat,long`
`av`	App Version	no	String used to log the version of your application
`dbg`	Debug	no	Set the debug flag to “true” to indicate development data or to “false” to indicate production data.

The following attributes only apply if dt is ScreenView:

Attribute	Name	Required	Description
`hn`	Hostname	no	The hostname for your page
`ttl`	Title	no	The title of your page

Supported event types

At present, the Pixel Service supports the following event types:

Custom Events - Custom Events
ScreenView - Page View Events

When sending an event as a Custom Event (dt), you must also provide a Custom Event Type (et) within the payload.

Some examples may be:

Navigation
Location
Search
Transaction
UserContent
UserPreference
Social
Other

For a more comprehensive list, please refer to our Custom Events documentation.

Comma separated values: attributes and user identities

For Comma separated values, such as event attributes, user attributes and user identity key/value pairs, the key and value must be submitted separately.

For example:

// User Identities
{
    "email": "test@email.com",
    "customerId": "1234567",
    "phone_number": "212-555-1212"
}

Should be uploaded as:

ui_t=email,customerid,phone_number&ui_v=test@email.com,1234567,212-555-1212

Was this page helpful?