Amazon Pinpoint Endpoints in putEvents-Method of the JavaScript SDK aren't working

Question

I've built a AWS Pinpoint integration into my app using API Gateway and Events are properly coming into Pinpoint. However with every new request a new Endpoint is created although I supply the "address"-field.

I went through all the docs provided by AWS:

https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-events.html

https://docs.aws.amazon.com/pinpoint/latest/developerguide/integrate-events.html

Primarily used this class doc which seems to have some missing info:

https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Pinpoint.html

async function putEvent(clientRequest){
    /* create the putEvents parameters */
    var param = {
        ApplicationId: PINPOINT_APP_ID,
        EventsRequest: {
            BatchItem: { }
        }
    };

    /* create the event parameter */
    var eventParam = {
        Endpoint: {
            Address: clientRequest.deviceId,
            ChannelType: 'CUSTOM',
            Demographic: {
                AppVersion: clientRequest.app.version,
                Locale: clientRequest.system.locale,
                Make: clientRequest.device.manufacturer,
                Model: clientRequest.device.model,
                ModelVersion: clientRequest.device.version,
                Platform: clientRequest.platform.name,
                PlatformVersion: clientRequest.platform.version
            }
        }
    };

    /* add the location if its was provided */
    if(clientRequest.hasOwnProperty('location')){
        /* add the latitude and longitude values */
        eventParam.Endpoint['Location'] = {
            Latitude: clientRequest.location.latitude,
            Longitude: clientRequest.location.longitude
        }

        /* check if a city and postal code was supplied
            alongside the country value */
        if(clientRequest.location.hasOwnProperty('cityName') == true
            && clientRequest.location.hasOwnProperty('countryCode') == true
            && clientRequest.location.hasOwnProperty('postalCode') == true){
            /* attach to the location param */
            eventParam.Endpoint.Location['Country'] = clientRequest.location.countryCode;
            eventParam.Endpoint.Location['City'] = clientRequest.location.postalCode;
            eventParam.Endpoint.Location['PostalCode'] = clientRequest.location.cityName;
        }
    }

    /* check if the userId was supplied */
    if(clientRequest.hasOwnProperty('userId')){
        /* attach the hashed and salted user id */
        eventParam.Endpoint['User'] = {UserId: getSHA512(clientRequest.userId+USERID_HASHSALT)};
    }

    /* attach the event values */
    eventParam['Events'] = [{
        EventType: clientRequest.event.name,
        Timestamp: (new Date()).toISOString()
    }];

    /* create a unique request id */
    var requestId = (new Date().getTime()) + Math.floor(Math.random() * 10);
    param.EventsRequest.BatchItem[requestId] = eventParam;

    /* flush an event to Pinpoint */
    await Pinpoint.putEvents(param).promise();
}

After every request I do have a new Pinpoint Endpoint defined, although I provide a unique Address-value for each Endpoint.

a) What do I need to do have the Endpoints unique?

b) How can I report Sign-ins, Sign-out and the other Events?

^ Could not find them in the documentation

Answer 1

Agreed the Pinpoint docs / class document is incomplete leaving out desired information. From my experiencing testing & using the API this is what I have found which hopefully can be of use.

a) What do I need to do have the Endpoints unique?

Pinpoint.putEvents not only creates a new event for an endpoint but it also creates or updates endpoint data

The fact that Pinpoint.putEvents can create or update an endpoint is causing the error you've encountered where a new endpoint is created after every event request.

This is because you are accidentally creating a new endpoint equal to the random requestId for each event that you send when setting the keys of BatchItem. The object keys of BatchItem are actually supposed to be the endpointId the event is supposed to be associated with opposed to the requestId for the event (This is not mentioned at all in the docs!)

To keep endpoints unique you first need to know what the unique endpoint is for the user in addition to the address and unique UserId (This seems to be missing from pinpoint docs. I realized it when trying to update or delete an endpoint which you cannot do by address as you need the endpointId). From your example I would choose something related to the userId concatenated with the channel type if you plan on having multiple channels for a single user as pinpoint does allow messages to be sent through email, sms and recorded voice calls (you've listed "CUSTOM" but I'd try to use one of the enum's that is actually associated with how the message would be delivered. I believe this allows this endpoint to work better with different types of pinpoint campaigns and journeys to send messages to your users)

    // Original code adding eventParam to param.EventsRequest.BatchItem incorrectly by random requestId
    var requestId = (new Date().getTime()) + Math.floor(Math.random() * 10);
    param.EventsRequest.BatchItem[requestId] = eventParam; 

   // correct code associating eventParam with a unique endpointId
    var endpointId = eventParam.Endpoint.User.UserId+'CUSTOM'
    param.EventsRequest.BatchItem[endpointId] = eventParam; 

Additionally keep in mind that all of the information you have added to eventParam.endpoint will update / overwrite whatever is currently stored for those endpointId attributes when calling Pinpoint.putEvents so watch out for that

b) How can I report Sign-ins, Sign-out and the other Events?

I believe to report sign-ins / sign-outs that are visualized in the pinpoint dashboard follow the event naming convention in the Pinpoint app events documentation

so for sign-ins the event name is _userauth.sign_in I don't think sign outs are displayed automatically on the Anlaytics -> Usage dashboard but you can use any consistent event name for sign outs and then use pinpoint filters to see those events through time.