15.2.9 Request Payloads

The Gala Analytics API is a strongly typed ingestion and requires that all input match DTO (Data Transfer Object) schemas. Validation will occur server-side and errors will be reported with 400 status codes in case of a mismatch.

It’s imperative that you catch and handle these errors if you’re using the API directly. The body of message returned from the server will specify the exact error encountered.

Payload structure consists of a common outer wrapper which is consistent across all reports, with an event-specific payload under the key details as shown below:

{
   user: 'string',
   // ...otherCommonFields
   details: {
      type: '<dtoName>',
      // ...dto specific fields
   }
}

Example Code

const axios = require('axios');


const ENVIRONMENT = 'test';
const PUBLISHER_ID = 'Ht3QOWhvthSZjamSOorRldkzgP7l4XbE';
const ANALYTICS_URI = 'https://<analytics-uri>/api/v1/report';


// session timer
const sessionStartTime = Date.now();


// example basic abstraction
const reportAnalyticsEvent = async (payload, publisherGroup = 'product') => {
    const reportUri = `/${publisherGroup}/${payload.details.type}`;


    // add time information
    payload.timestamp = Date.now();
    payload.elapsed = payload.timestamp - sessionStartTime;
    // this may be different if offline queuing
    payload.elapsedAtReportTime = payload.timestamp - sessionStartTime;
    payload.environment = ENVIRONMENT;


    return axios.post(reportUri, payload, {
        baseURL: ANALYTICS_URI,
        headers: {
            Authorization: `bearer ${btoa(PUBLISHER_ID)}`
        }
    });
};


// usage
(async () => {
    try {
        // report session start
        await reportAnalyticsEvent({
            userId: 'user1234',
            details: {
                sessionId: '123',
                type: 'SessionStartDTO'
            }
        });


        // report session ping
        await reportAnalyticsEvent({
            userId: 'user1234',
            details: {
                sessionId: '123',
                type: 'SessionPingDTO'
            }
        });


        // report session end
        await reportAnalyticsEvent({
            userId: 'user1234',
            details: {
                sessionId: '123',
                type: 'SessionEndDTO'
            }
        });


    } catch(err) {
        if(err.response) {
            // response body will contain validation failures
            console.log(err.response.status, err.response.data);
        } else { 
            console.log(err);
        }
    }
})();