Articles in this section

Real-Time Event Feed

Gail Des Jardin
Updated

Overview

MessageGears' real-time event feed provides a convenient way for you to receive account activity data in real-time as live events like clicks, opens, and bounces occur. This is useful for applications using MessageGears that need to capture their activity data more frequently than once a day (for example, for a job dashboard).

The data is formatted in one of two ways:

  • Using the same XML structure as the AccountActivity API results. The only difference is that the data will come from a queue in many small XML payloads.
  • Optionally, as a comma-delimited CSV file on the SQS feed.
XML data formats only populate data returned for each activity, while CSV formats include every header in each activity, regardless of whether it contains data (for example, correlationId or campaignId).

The available activity data relies on the real-time event feed configuration available in Accelerator. The activity types include: 

Message delivery

Hosted data

Mobile application

For mobile application events, the mobile app must have a complete MessageGears mobile SDK integration. For more information, contact your CSM representative.

Process

Implementation

Amazon provides their Simple Queue Service as a way to easily and securely transfer data using their API.

Response values

Common response values for the v3.1 event feed:

Element Name

Description

ActivityItems

The root element of the XML response.

RequestId

The MessageGears request id of the job of which the activity items belongs.

ActivityId

The unique activity id for an individual activity item.

Timestamp

The time that the event/activity item occurred.

EmailAddress

The email address of the recipient responsible for the activity item.

IpAddress

The ip address that generated the activity.

CorrelationId (Optional)

The correlation id provided with the invocation of this job, if supplied. This field allows you to supply your own job id. This ID is designed to make it easier to match events coming out of MessageGears with the job they belong to in your own system.

RecipientId (Optional)

The Recipient ID for the recipient that generated an event. The Recipient ID is intended to be a unique identifier for each recipient in your source data, providing reporting metrics without the need to display PII.

JobCategory (Optional)

The category for that job invocation, if supplied. The job category creates the opportunity for unique and aggregate job reporting using detailed event information.

Email activities

The following is a sample of the activities related to the email channel.

Click activity

<ActivityItems>
 <ClickActivity>
  <RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-14T15:50:19.491-04:00</Timestamp>
  <IpAddress>74.60.196.56</IpAddress>
  <UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>
  <Url>http://www.mycompany.com</Url>
  <UrlId>this is the url id</UrlId>
  <UrlName>Home Page</UrlName>
  <Microsite>true</Microsite>
 </ClickActivity>
</ActivityItems>

Element Name

Description

ClickActivity

The element containing all the click information. This is a repeating element, one for each click event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Url

The URL of the clicked link.

UrlName

The name (if any) of the link you provided in the template when the link was made trackable.

Microsite

Will be set to "true" if this event originated from a microsite version of an email message.

Open activity

<ActivityItems>
 <OpenActivity>
  <RequestId>t25710-07bc4beb-34de-44d1-85b0-d27628a78b2c</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-14T15:49:16.064-04:00</Timestamp>
  <IpAddress>74.60.196.56</IpAddress>
  <UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>
  <Microsite>true</Microsite>
 </OpenActivity>
</ActivityItems>

Element Name

Description

OpenActivity

The element containing all the open information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Delivery activity

<ActivityItems>
 <DeliveredMessageActivity>
  <RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>
  <IpAddress>74.125.47.27</IpAddress>
 </DeliveredMessageActivity>
</ActivityItems>

Element Name

Description

DeliveredMessageActivity

The element containing all the delivery information. This is a repeating element, one for each email delivered for the specified day.

Bounce activity

<ActivityItems>
 <BouncedMessageActivity>
  <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>
  <Category>Invalid Recipient</Category>
  <CategoryCode>10</CategoryCode>
  <Details>550-5.1.1 The email account that you tried to reach does not exist.</Details>
  <IpAddress>74.125.47.27</IpAddress>
 </BouncedMessageActivity>
</ActivityItems>

Element Name

Description

BouncedMessageActivity

The element containing all the bounce information. This is a repeating element, one for each bounce event for the specified day.

Category

A general category of the bounce.

CategoryCode

A unique code that identifies the category of the bounce.

Details

The detailed bounce message.

Bounce categories

Please remove all bounces of type 10 and 30. Failure to do so may negatively impact your inbox performance with the various ISPs.

Category

Category Code

Description

Undetermined

1

The response text could not be identified.

Invalid Recipient

10

The recipient is invalid.

Soft Bounce

20

The message soft bounced.

DNS Failure

21

The message bounced due to a DNS failure.

Mailbox Full

22

The message bounced due to the remote mailbox being over quota.

Too Large

23

The message bounced because it was too large for the recipient.

Timeout

24

The message timed out.

Admin Failure

25

The message was failed by configured policies.

Generic Bounce: No RCPT

30

No recipient could be determined for the message.

Generic Bounce

40

The message failed for unspecified reasons.

Mail Block

50

The message was blocked by the receiver.

Spam Block

51

The message was blocked by the receiver as coming from a known spam source.

Spam Content

52

The message was blocked by the receiver as spam.

Prohibited Attachment

53

The message was blocked by the receiver because it contained an attachment.

Relay Denied

54

The message was blocked by the receiver because relaying is not allowed.

Transient Failure

70

Message transmission has been temporarily delayed.

Invalid Email Syntax

110

The message has a malformed/invalid email address.

Hardbounce Suppression

130

The message is a known-bad email address and has hard-bounces with a category 10 or 30 in the past. It was suppressed from sending to protect IP reputation with the ISP.

Unsubscribe Suppression

131

The recipient of the message has unsubscribed from a message from your account in the past. It was suppressed from sending to protect your sending reputation.

Fbl Suppression

132

The recipient of the message has filed a spam complaint with your account in the past. It was suppressed from sending to protect your sending reputation.

Complainer Suppression

133

The recipient of the message is a known complainer. It was suppressed from sending to protect your sending reputation.

Domain Suppression

134

The recipient domain is not allowed. It was suppressed from sending to protect your sending reputation.

Role Suppression

135

The recipient address is not allowed. It was suppressed from sending to protect your sending reputation.

Unsubscribe activity

<ActivityItems>
 <UnsubActivity>
  <RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>
  <IpAddress>128.234.11.12</IpAddress>
  <UserAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.17.8 (KHTML, like Gecko) Version/5.0.1 Safari/533.17.8</UserAgent>
 </UnsubActivity>
</ActivityItems>

Element Name

Description

UnsubActivity

The element containing all the unsub information. This is a repeating element, one for each open event for the specified day.

UserAgent

The browser type (or email client) used to provide the event.

Microsite

Will be set to “true” if this event originated from a microsite version of an email message.

Spam complaint activity

<ActivityItems>
 <SpamComplaintActivity>
  <RequestId>t25810-eec987c5-085b-4d40-a4ce-24a5850638a5</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-15T16:14:46.878-04:00</Timestamp>
  <Isp>gmail.com</Isp>
 </SpamComplaintActivity>
</ActivityItems>

Element Name

Description

SpamComplaintActivity

The element containing the Spam Complaint information. This is a repeating element, one for each complaint received for the specified day.

Isp

The domain part of the recipient’s email address.

Job error activity

<ActivityItems>
 <JobErrorActivity>
  <RequestId>t25710-9540c8d8-aa5d-44d7-a9ef-a334072df515</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <Timestamp>2010-09-14T13:20:36.994-04:00</Timestamp>
  <JobError>
   <ErrorCode>Transfer Error</ErrorCode>
   <ErrorMessage>AmazonClientException retrieving file: s3://mycompany/myfile.txt - The specified key does not exist.</ErrorMessage>
  </JobError>
 </JobErrorActivity>
</ActivityItems>

Element Name

Description

JobErrorActivity

The element containing theJob Error information. This is a repeating element, one for each job that failed to be processed for the specified day.

JobError

A repeating element, one for each error that occurred.

ErrorCode

A general error code for the failure.

ErrorMessage

A detailed error description.

Render error activity

<ActivityItems>
 <RenderErrorActivity>
  <RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <EmailAddress>joe@gmail.com</EmailAddress>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <RenderErrors>
   <RenderError>
    <ErrorCode>Template merge exception</ErrorCode>
    <ErrorMessage>Error on line 1, column 10 in SUBJECT Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>
   </RenderError>
  </RenderErrors>
 </RenderErrorActivity>
</ActivityItems>

Element Name

Description

RenderErrorActivity

The element containing the error information regarding the rendering of an email message. This is a repeating element, one for each email that failed to be rendered for the specified day.

Error Code

A general error code for the failure.

ErrorMessage

A detailed error description.

Mobile push activities

Depending on the push vendor, there may be various activity types available for push notifications. The following are examples of common mobile push activities.

Push delivery

<ActivityItems>
 <DeliveredMobilePushActivity>
  <RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <DeviceId>123456789</DeviceId>
  <Service>APNS</Service>
  <ApplicationId>12345</ApplicationId>
  <Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>
  <PushDeliveryService>AWS Pinpoint</PushDeliveryService>
 </DeliveredMobilePushActivity>
</ActivityItems>

Push delivery failure

<ActivityItems>
 <BouncedMobilePushActivity>
  <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <DeviceId>12345678</DeviceId>
  <Service>APNS</Service>
  <ApplicationId>12345</ApplicationId>
  <Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>
  <Category>AWS Pinpoint Category, such as "TRANSIENT_FAILURE"</Category>
  <Details>A temporary error occurred. MessageGears will attempt to deliver the message again later.</Details>
  <PushDeliveryService>AWS Pinpoint</PushDeliveryService>
 </BouncedMobilePushActivity>
</ActivityItems>

The possible values for Category and Details are:

Category

Details

TRANSIENT_FAILURE

A temporary error occurred. MessageGears will attempt to deliver the message again later.

FAILURE_PERMANENT

An error occurred when delivering the message to the endpoint. MessageGears won’t attempt to send the message again.

TIMEOUT

The message couldn’t be sent within the timeout period.

DAILY_CAP

The endpoint has received the maximum number of messages it can receive within a 24-hour period.

THROTTLED

MessageGears throttled sending to this endpoint.

EXPIRED

The endpoint address is expired.

SERVICE_FAILURE

A service-level failure prevented MessageGears from delivering the message.

JOB_CANCELLED

The job has been cancelled

Push render error

<ActivityItems>
 <RenderErrorMobilePushActivity>
  <RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <DeviceId>12345678</DeviceId>
  <Service>APNS</Service>
  <ApplicationId>12345</ApplicationId>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <RenderErrors>
   <RenderError>
    <ErrorCode>Template merge exception</ErrorCode>
    <ErrorMessage>Error on line 1, column 10 in SUBJECT Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>
   </RenderError>
  </RenderErrors>
 </RenderErrorMobilePushActivity>
</ActivityItems>

Push click

<ActivityItems>
 <ClickedMobilePushActivity>
  <AccountId>23295228</AccountId>
  <RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <JobCategory>the job category</JobCategory>
  <CampaignId>12345123</CampaignId>
  <CampaignVersion>1001</CampaignVersion>
  <ActivityId>421d9fec-a1ad-400c-9a91-7afa40accffe</ActivityId>
  <RecipientId>Sonic the Hedgehog &amp; His Buddy Tails</RecipientId>
  <Destination>my-swrve-push-url</Destination>
  <Service>android</Service>
  <ApplicationId>33</ApplicationId>
  <Timestamp>1970-01-10T01:13:20.000-05:00</Timestamp>
  <PushDeliveryService>Swrve</PushDeliveryService>
  <MobileUserId>mobileUserId-123</MobileUserId>
  <VendorAppId>swrve12345</VendorAppId>
 <ActivityItems>
</ClickedMobilePushActivity>

SMS activities

SMS Delivery

SMS Delivery confirmations detail the delivery details for each outbound message. Any unsuccessful message transmissions will result in a delivery failure (see below):

<ActivityItems>
 <DeliveredSmsActivity>
  <RequestId>t25610-3147e501-c83f-42a5-b638-c476e1237a65</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>123456789</DeviceId>
  <Timestamp>2010-09-13T18:51:00.000-04:00</Timestamp>
 </DeliveredSmsActivity>
</ActivityItems>

SMS Render Error

<ActivityItems>
 <RenderErrorSmsActivity>
  <RequestId>t25610-0b74f4c6-fe21-411f-bba9-82818bf1c31b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>12345678</SmsAddress>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <RenderErrors>
   <RenderError>
    <ErrorCode>Template merge exception</ErrorCode>
    <ErrorMessage>Error on line 1, column 10 in BODY Expecting a string, date or number here, Expression Recipient.FirstNamex is instead a freemarker.ext.dom.NodeListModel</ErrorMessage>
   </RenderError>
  </RenderErrors>
 </RenderErrorSmsActivity>
</ActivityItems>

SMS Delivery Failure

<ActivityItems>
 <BouncedSmsActivity>
  <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
  <CorrelationId>My Job Id: 101010</CorrelationId>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>12345678</SmsAddress>
  <Timestamp>2010-09-13T19:10:54.000-04:00</Timestamp>
  <Category>Sms Failure category, such as "INVALID_ADDRESS"</Category>
  <Details>The phone number you have attempted to send to is not valid or unrecognizable to our system.</Details>
 </BouncedSmsActivity>
</ActivityItems>

The possible values for Category and Details are:

Category

Details

INVALID_ADDRESS

The phone number you have attempted to send to is not valid or unrecognizable to our system

INTERNATIONAL_SENDING_PROHIBITED

International message sending is not enabled for your account. Please contact support to send to this number

ADDRESS_BLOCKED

The message could not be sent from this OriginationNumber to the destination address

INVALID_CONTENT

This content is unable to be sent as an SMS message

SERVICE_FAILURE

A service-level failure prevented MessageGears from delivering the message

JOB_CANCELLED

The job has been cancelled

SMS Inbound Message

<ActivityItems>
 <InboundSmsActivity>
  <ActivityId>57e01e05-f10c-48aa-bd29-8a0912e72d40</ActivityId>
  <SmsAddress>12345678</SmsAddress>
  <Timestamp>2010-09-13T19:13:46.220-04:00</Timestamp>
  <To>12345</To>
  <InboundMessageType>STOP</InboundMessageType>
  <InboundMessage>The inbound message sent from the recipient, such as "STOP", "HELP", or a Keyword</InboundMessage>
 </InboundsmsActivity>
</ActivityItems>

In-app message Activities

The following is a sample of the activities related to the in-app message channel.

Common response values for In-app message activities: 

Element Name

Description

Platform

The platform (OS) the message was displayed on.

Device

The type of device (mobile or TV) the message was displayed on. 

PageId

The ID of the page viewed.

PageName

The name of the page viewed.

VendorAppId

The ID of the mobile app that generated the event. 

In-app message Impression

<ActivityItems>
 <ImpressionInAppMessageActivity>
  <Timestamp>1970-01-10T01:13:20.000-05:00</Timestamp>
  <ActivityId>421d9fec-a1ad-400c-9a91-7afa40accffe</ActivityId>
  <InAppCampaignId>iam-campaign-123</InAppCampaignId>
  <InAppTrackingId>iam-tracking-123</InAppTrackingId>
  <ClientCampaignId>113355</ClientCampaignId>
  <CampaignUuid>the campaign uuid</CampaignUuid>
  <DeviceId>deviceId</DeviceId>
  <ApplicationId>54321</ApplicationId>
  <VendorAppId>swrve12345</VendorAppId>
  <RecipientId>swrve-external-user</RecipientId>
  <Platform>ios</Platform>
  <DeviceType>mobile</DeviceType>
  <MobileUserId>mobileUserId-123></MobileUserId>
  <Category>the job category</Category>
 </ImpressionInAppMessageActivity>
</ActivityItems>

Element Name

Description

ImpressionInAppMessageActivity

The element containing all the impression information. This is a repeating element, one for each time an an in-message is displayed to the user. 

In-app message Page View

<ActivityItems>
 <PageViewedInAppMessageActivity>
  <Timestamp>1970-01-10T01:13:20.000-05:00</Timestamp>
  <ActivityId>421d9fec-a1ad-400c-9a91-7afa40accffe</ActivityId>
  <InAppCampaignId>iam-campaign-123</InAppCampaignId>
  <InAppTrackingId>iam-tracking-123</InAppTrackingId>
  <ClientCampaignId>113355</ClientCampaignId>
  <CampaignUuid>the campaign uuid</CampaignUuid>
  <DeviceId>deviceId</DeviceId>
  <ApplicationId>54321</ApplicationId>
  <VendorAppId>swrve12345</VendorAppId>
  <RecipientId>swrve-external-user</RecipientId>
  <Platform>ios</Platform>
  <DeviceType>mobile</DeviceType>
  <MobileUserId>mobileUserId-123</MobileUserId>
  <PageId>page001</PageId>
  <PageName>My Iam Landing Page</PageName>
  <Category>the job category</Category>
 </PageViewedInAppMessageActivity>
</ActivityItems>

Element Name

Description

PageViewedInAppMessageActivity

The element containing all the page view information. This is a repeating element, one for each time a unique in-app message page is viewed.

In-app message Click

<ActivityItems>
 <ClickedInAppMessageActivity>
  <Timestamp>1970-01-10T01:13:20.000-05:00</Timestamp>
  <ActivityId>421d9fec-a1ad-400c-9a91-7afa40accffe</ActivityId>
  <InAppCampaignId>iam-campaign-123</InAppCampaignId>
  <InAppTrackingId>iam-tracking-123</InAppTrackingId>
  <ClientCampaignId>113355</ClientCampaignId>
  <CampaignUuid>the campaign uuid</CampaignUuid>
  <DeviceId>deviceId</DeviceId>
  <ApplicationId>54321</ApplicationId>
  <VendorAppId>swrve12345</VendorAppId>
  <RecipientId>swrve-external-user</RecipientId>
  <Platform>ios</Platform>
  <DeviceType>mobile</DeviceType>
  <MobileUserId>mobileUserId-123</MobileUserId>
  <PageId>page001</PageId>
  <PageName>My Iam Landing Page</PageName>
  <ButtonId>button001</ButtonId>
  <ButtonName>My Iam Button</ButtonName>
  <Category>the job category</Category>
 </ClickedInAppMessageActivity>
</ActivityItems>

Element Name

Description

ClickedInAppMessageActivity

The element containing all the button click information. This is a repeating element, one for each time an in-app message element containing a non-page navigation, non-dismiss action is clicked. 

ButtonId

The ID of the clicked button.

ButtonName

The name of clicked button.

In-app message Dismiss

<ActivityItems>
 <DismissedInAppMessageActivity>
  <Timestamp>1970-01-10T01:13:20.000-05:00</Timestamp>
  <ActivityId>421d9fec-a1ad-400c-9a91-7afa40accffe</ActivityId>
  <InAppCampaignId>iam-campaign-123</InAppCampaignId>
  <InAppTrackingId>iam-tracking-123</InAppTrackingId>
  <ClientCampaignId>113355</ClientCampaignId>
  <CampaignUuid>the campaign uuid</CampaignUuid>
  <DeviceId>deviceId</DeviceId>
  <ApplicationId>54321</ApplicationId>
  <VendorAppId>swrve12345</VendorAppId>
  <RecipientId>swrve-external-user</RecipientId>
  <Platform>ios</Platform>
  <DeviceType>mobile</DeviceType>
  <MobileUserId>mobileUserId-123</MobileUserId>
  <PageId>page001</PageId>
  <PageName>My Iam Landing Page</PageName>
  <ButtonId>button001</ButtonId>
  <ButtonName>My Iam Button</ButtonName>
  <Category>the job category</Category>
 </DismissedInAppMessageActivity>
</ActivityItems>

Element Name

Description

DismissedInAppMessageActivity

The element containing all the dismiss information. This is a repeating element, one for each time an in-app message is dismissed. 

ButtonId

The ID of the button clicked to dismiss the campaign. If empty, then the message was dismissed by the device's dismiss control.

ButtonName

The name of the button clicked to dismiss the campaign. If empty, then the message was dismissed by the device's dismiss control.

In-app message Page Navigation

<ActivityItems>
 <PageNavigationInAppMessageActivity>
  <Timestamp>1970-01-10T01:13:20.000-05:00</Timestamp>
  <ActivityId>421d9fec-a1ad-400c-9a91-7afa40accffe</ActivityId>
  <InAppCampaignId>iam-campaign-123</InAppCampaignId>
  <InAppTrackingId>iam-tracking-123</InAppTrackingId>
  <ClientCampaignId>113355</ClientCampaignId>
  <CampaignUuid>the campaign uuid</CampaignUuid>
  <DeviceId>deviceId</DeviceId>
  <ApplicationId>54321</ApplicationId>
  <VendorAppId>swrve12345</VendorAppId>
  <RecipientId>swrve-external-user</RecipientId>
  <Platform>ios</Platform>
  <DeviceType>mobile</DeviceType>
  <MobileUserId>mobileUserId-123</MobileUserId>
  <PageId>page001</PageId>
  <PageName>My Iam Landing Page</PageName>
  <ButtonId>button001</ButtonId>
  <ButtonName>My Iam Button</ButtonName>
  <Category>the job category</Category>
 </PageNavigationInAppMessageActivity>
</ActivityItems>

Element Name

Description

PageNavigationInAppMessageActivity

The element containing all the page navigation information. This is a repeating element, one for each time a page navigation button is clicked. 

ButtonId

The ID of the page navigation button clicked. 

ButtonName

The name of the page navigation button clicked. 

Hosted data activities

Hosted Data Hit

Hosted (formerly Context) Data Hit events are created for requests to the Engage API that successfully return records. For multi-key requests, an event is generated for each requested record that was found. For requests sent using our Campaigns product, a RequestId will be included. Additionally, for Campaign requests, a CorrelationId and RecipientId will also be included if they were present.

<ActivityItems>
 <ContextHitActivity>
 <Timestamp>2020-09-22T16:59:39Z</Timestamp>
 <AccountId>23295228</AccountId>
 <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
 <CorrelationId>Your Correlation Id</CorrelationId>
 <ActivityId>496517a3-1687-4d95-1011-ccd93ff7f540</ActivityId>
 <RecipientId>Your Recipient Id</RecipientId>
 <IpAddress>1.2.3.4</IpAddress>
 <Vendor>2</Vendor>
 <Prefix>DEMO2</Prefix>
 <RecordId>DEMO2-ofYlGLFP9e5HfcfI40l6TFoJtouGecQIr8nT</RecordId>
 <RecordSize>4107</RecordSize>
 <CreateTimestamp>2020-09-09T16:38:10Z</CreateTimestamp>
 <UpdateTimestamp>2020-09-09T16:38:10Z</UpdateTimestamp>
 </ContextHitActivity>
</ActivityItems>

Hosted Data Miss

Hosted (formerly Context) Data Miss events are created for requests to the Engage API that fail to return records. For multi-key requests, an event is generated for each requested record that was not found. For requests sent using our Campaigns product, a RequestId will be included. Additionally, for campaign requests, a CorrelationId and RecipientId will also be included if they were present.

<ActivityItems>
 <ContextHitActivity>
 <Timestamp>2020-09-22T16:59:39Z</Timestamp>
 <AccountId>23295228</AccountId>
 <RequestId>t25610-2d7e1a55-f161-4af1-8f33-c994a0327a8b</RequestId>
 <CorrelationId>Your Correlation Id</CorrelationId>
 <ActivityId>496517a3-1687-4d95-1011-ccd93ff7f540</ActivityId>
 <RecipientId>Your Recipient Id</RecipientId>
 <IpAddress>1.2.3.4</IpAddress>
 <Vendor>2</Vendor>
 <Prefix>DEMO2</Prefix>
 <RecordId>DEMO2-ofYlGLFP9e5HfcfI40l6TFoJtouGecQIr8nT</RecordId>
 </ContextHitActivity>
</ActivityItems>

Mobile application activities

The mobile SDK captures specific user activities immediately on app open. These activities are processed and made available on the real-time event feed. The following are sample mobile app activities.

Mobile user first session 

When a user installs and uses the push app for the first time, a first session event occurs. At this point a user is classified as a new user and is assigned a mobileUserID, often referred to as the SwrveUserID. 

This is a lightweight event as our knowledge about the user or their device is limited at this time. The SDK will capture the device properties and pass this data back using a device properties update event that occurs immediately after the first session event.

<ActivityItems>
 <MobileUserFirstSessionActivity>
  <ActivityId>UUID</ActivityId>
  <ApplicationId>SomeApplication</ApplicationId>
  <DeviceId>SomeUniqueId</DeviceId>
  <MobileAppId>1</MobileAppId>
  <MobileUserId>SomeMobileUser</MobileUserId>
  <Timestamp>1970-01-01T00:00:00.002Z</Timestamp>
  <UserType>SomeUserType</UserType>
 </MobileUserFirstSessionActivity>
</ActivityItems>
Element Name Description
ActivityId The unique activity ID for an individual activity item.
ApplicationId The customer's Accelerator application ID.
DeviceId The device ID from which the event/activity originated.
MobileAppId The push application from which the event/activity originated.
MobileUserId A unique user ID assigned to the user of the push app.
UserType This indicates whether the user is anonymous, known, or orphaned.
Timestamp The time the event/activity occurred.

start 

After the first session occurs for a user, every subsequent app open will produce a session event.

This event indicates user activity within the app and forms part of the frequency and recency calculations for segmentation.  It is a lightweight event and as per the first session, a device property update event occurs immediately after this event to ensure the mobile platform has the most up to date information about the user’s device.

<ActivityItems>
 <MobileUserSessionStartActivity>
  <ActivityId>UUID</ActivityId>
  <ApplicationId>SomeApplication</ApplicationId>
  <DeviceId>SomeUniqueId</DeviceId>
  <MobileAppId>1</MobileAppId>
  <MobileUserId>SomeMobileUser</MobileUserId>
  <RecipientId>SomeRecipient</RecipientId>
  <Timestamp>1970-01-01T00:00:00.002Z</Timestamp>
  <UserType>SomeUserType</UserType>
 </MobileUserSessionStartActivity>
</ActivityItems>
Element name Description
ActivityId The unique activity ID for an individual activity item.
ApplicationId The customer’s Accelerator application ID.
DeviceId The device ID from which the event/activity originated.
MobileAppId The push application from which the event/activity originated.
MobileUserId A unique user ID assigned to the user of the push app.
UserType This indicates if the user is anonymous, known, or orphaned.
Timestamp The time the event/activity occurred.

Mobile device update 

On opening the app where the SDK initiated, a device update event is triggered that  passes the properties that are available on the device. Such properties include the device name, model, OS and OS version, permissions, and other physical characteristics of the device. Each time the user opens the app, this event occurs to ensure all property values are known. This is important, as the user can change settings between sessions and the mobile platform relies on these properties to deliver in-app and out of app experiences to the user.

<ActivityItems>
 <MobileUserDeviceUpdateActivity>
  <ActivityId>UUID</ActivityId>
  <ApplicationId>SomeApplication</ApplicationId>
  <DeviceId>UniqueDeviceId</DeviceId>
  <MobileAppId>1</MobileAppId>
  <MobileUserId>SomeMobileUser</MobileUserId>
  <RecipientId>SomeUser</RecipientId>
  <Timestamp>1970-01-01T00:00:00.002Z</Timestamp>
  <UserType>SomeUserType</UserType>
  <DeviceType>DeviceType</DeviceType>
  <DeviceName>DeviceName</DeviceName>
  <Region>Region</Region>
  <Language>Language</Language>
  <Platform>Platform</Platform>
  <PlatformVersion>PlatformVersion</PlatformVersion>
  <DeviceTimezoneName>TimezoneName</DeviceTimezoneName>
  <MobileSdkVersion>SdkVersion</MobileSdkVersion>
  <AppStore>AppStore</AppStore>
  <InstallDate>InstallDate</InstallDate>
  <UtcOffset>UtcOffsetSeconds</UtcOffset>
  <IosPushPermission>IosPushPermission</IosPushPermission>
  <BackgroundPushPermissions>BackgroundPushPermissions</BackgroundPushPermissions>
  <CameraPermission>CameraPermission</CameraPermission>
  <ContactsPermission>ContactsPermission</ContactsPermission>
  <PhotosPermission>PhotosPermission</PhotosPermission>
  <LocationAlwaysPermission>LocationAlwaysPermission</LocationAlwaysPermission>
  <LocationInUsePermission>LocationInUsePermission</LocationInUsePermission>
  <LocationAccuracyPermission>LocationAccuracyPermission</LocationAccuracyPermission>
  <IosPushToken>iosPushToken</IosPushToken>
  <SupportRichGif>SupportRichGif</SupportRichGif>
  <MobileSdkFlavor>MobileSdkFlavor</MobileSdkFlavor>
  <PushPermissionEnabled>PushPermissionEnabled</PushPermissionEnabled>
  <PushImportance>PushImportance</PushImportance>
  <AndroidPushPermission>AndroidPushPermission</AndroidPushPermission>
  <PermissionShowRationale>PermissionShowRationale</PermissionShowRationale>
  <PermissionAnsweredTimes>PermissionAnsweredTimes</PermissionAnsweredTimes>
  <GcmPushToken>GcmPushToken</GcmPushToken>
  <LocationServiceEnabled>LocationServiceEnabled</LocationServiceEnabled>
 </MobileUserDeviceUpdateActivity>
</ActivityItems>
Element name Description
ActivityId The unique activity ID for an individual activity item.
ApplicationId The customer's Accelerator application ID.
DeviceId The device ID from which the event/activity originated.
MobileAppId The push application from which the event/activity originated.
MobileUserId A unique user ID assigned to the user of the push app.
RecipientId The Recipient ID for the recipient that generated an event. The Recipient ID is intended to be a unique identifier for each recipient in your source data, providing reporting metrics without the need to display PII.
Timestamp The time the event/activity occurred.
UserType This indicates if the user is anonymous, known, or orphaned.
DeviceType The type of device used to generate the event/activity. For example, mobile, TV, or Web.
DeviceName The name of the device.
Region The 2-letter ISO country code of the selected region of the device.
Language The language of the device.
Platform The operating system of the device.
DeviceTimezoneName The timezone name for the user taken from the device.
MobileSdkVersion The mobile SDK version being used.
AppStore The name of the app store used.
InstallDate Integer value generated on device when the app is first run, in format: yyyymmdd.
UtcOffset The number of seconds offset from UTC.
IosPushPermission The user’s push notifications permission status. Possible string values are unknown, unsupported, denied, or authorized [iOS users only].
BackgroundPushPermissions The user’s background update permission status.
CameraPermission The user’s camera permission status. Possible string values are unknown, unsupported, denied, or authorized [iOS users only].
ContactsPermission The user’s contact permission status. Possible string values are unknown, unsupported, denied, or authorized [iOS users only].
PhotosPermission The user’s photo permission status. Possible string values are unknown, unsupported, denied, or authorized [iOS users only].
LocationAlwaysPermission The user’s location permission status (when in use). Possible string values are unknown, unsupported, denied, or authorized [Geo SDK only].
LocationInUsePermission The user’s location permission status (when in use). Possible string values are unknown, unsupported, denied, or authorized [Geo SDK only].
LocationAccuracyPermission The user's location accuracy setting. Possible string values are full or reduced [Geo SDK only].
IosPushToken The push address (token) assigned to the device [iOS devices only].
SupportRichGif The device support for rich media content.
PushPermissionEnabled The device push permission settings.
PushImportance The importance setting for the push notification [Android only].
AndroidPushPermission The user’s notification permission status. Possible string values are denied or granted. User property is only set for devices on Android 13 or higher.
PermissionShowRationale

Indicates whether the permission dialog was previously shown. Returns true if the permission dialog was shown once and the user denied it (not dismissed). Returns false if permission dialog was never shown, or if it was shown but the user dismissed it without granting or denying it, or was shown/responded to twice, or if permission was already granted.

User property is only set for devices on Android 13 or higher.
PermissionAnsweredTimes The number of times the user has answered the permission request. A dismissal is not counted—the user must respond by granting or denying permission. Possible integer values are 0, 1, or 2.
GcmPushToken The push address (token) assigned to the device [Android devices only].
LocationServiceEnabled The location service status.

Push permissions

To ensure the user is open to receiving push notifications, they must grant push permissions for the push app on the device. When the user sets the permission, an event occurs for both iOS and Android for each permission value: granted or denied. For user profile updates in the customer data warehouse, the permission can be set by a device update or explicitly by push permission events. Both event types should be taken into consideration when updating the user’s push permission.

<ActivityItems>
 <MobileUserPushPermissionUpdateActivity>
  <ActivityId>UUID</ActivityId>
  <ApplicationId>SomeApplication</ApplicationId>
  <DeviceId>SomeUniqueId</DeviceId>
  <MobileAppId>1</MobileAppId>
  <MobileUserId>SomeMobileUser</MobileUserId>
  <PushPermission>granted</PushPermission>
  <RecipientId>SomeRecipient</RecipientId>
  <Timestamp>1970-01-01T00:00:00.002Z</Timestamp>
  <UserType>SomeUserType</UserType>
 </MobileUserPushPermissionUpdateActivity>
</ActivityItems>
Element name Description
ActivityId The unique activity ID for an individual activity item.
ApplicationId The customer’s Accelerator application ID.
DeviceId The device ID from which the event/activity originated.
MobileAppId The push application from which the event/activity originated.
MobileUserId A unique user ID assigned to the user of the push app.
UserType This indicates if the user is anonymous, known, or orphaned.
RecipientId The Recipient ID for the recipient that generated an event. The Recipient ID is intended to be a unique identifier for each recipient in your source data, providing reporting metrics without the need to display PII.
PushPermission The user’s push notification permission status.
Timestamp The time the event/activity occurred.

Mobile user identity 

Most push apps require a user to register an amount and log in to gain access to the rich features on offer. When a user first downloads and installs the app they are assigned a mobileUserID. While using the app, all their behavior events are linked to this identifier. Once the user logs in using their credentials, their global user ID is then used to identify them via the identity API in the SDK. The identity event occurs when the user logs into their account on the mobile app. From this point onwards it is assumed the user is logged in until the identity API is called again.

<ActivityItems>
 <MobileUserIdentityUpdateActivity>
  <ActivityId>UUID</ActivityId>
  <ApplicationId>SomeApplication</ApplicationId>
  <DeviceId>SomeUniqueId</DeviceId>
  <MobileAppId>1</MobileAppId>
  <MobileUserId>SomeMobileUser</MobileUserId>
  <RecipientId>SomeRecipient</RecipientId>
  <Timestamp>1970-01-01T00:00:00.002Z</Timestamp>
  <UserType>SomeUserType</UserType>
 </MobileUserIdentityUpdateActivity>
</ActivityItems>
Element name Description
ActivityId The unique activity ID for an individual activity item.
ApplicationId The customer’s Accelerator application ID.
DeviceId The device ID from which the event/activity originated.
MobileAppId The push application from which the event/activity originated.
MobileUserId A unique user ID assigned to the user of the push app.
UserType This indicates if the user is anonymous, known, or orphaned.
RecipientId The Recipient ID for the recipient that generated an event. The Recipient ID is intended to be a unique identifier for each recipient in your source data, providing reporting metrics without the need to display PII.
Timestamp The time the event/activity occurred.

Mobile user custom events 

There are a number of user behaviors of interest to customers. Developers implement these events in the push app.  When the user performs the associated action, the mobile SDK processes and writes the event back to the server. At this point, the event is available for export to the customer environment.

<ActivityItems>
 <MobileUserCustomEventActivity>
  <ActivityId>UUID</ActivityId>
  <EventName>NewCustomEvent</EventName>
  <ApplicationId>SomeApplication</ApplicationId>
  <DeviceId>SomeUniqueId</DeviceId>
  <MobileAppId>1</MobileAppId>
  <MobileUserId>SomeMobileUser</MobileUserId>
  <RecipientId>SomeRecipient</RecipientId>
  <Timestamp>1970-01-01T00:00:00.002Z</Timestamp>
  <UserType>SomeUserType</UserType>
  <Payload>{"sample1":"v1","sample2":"v2","sample3":"v3"}</Payload>
 </MobileUserCustomEventActivity>
</ActivityItems>
Element name Description
ActivityId The unique activity ID for an individual activity item.
ApplicationId The customer’s Accelerator application ID.
EventName The name of the mobile user custom event.
DeviceId The device ID from which the event/activity originated.
MobileAppId The push application from which the event/activity originated.
MobileUserId A unique user ID assigned to the user of the push app.
UserType This indicates if the user is anonymous, known, or orphaned.
RecipientId The Recipient ID for the recipient that generated an event. The Recipient ID is intended to be a unique identifier for each recipient in your source data, providing reporting metrics without the need to display PII.
Payload  
Timestamp The time the event/activity occurred.

Mobile user property updates 

The mobile user profile has a number of user properties available and are set by the user via the push app. Developers implement these properties and set them based on the actions of the user. When a property is set during a user session, the mobile SDK processes it as a user property update event and writes it back to the server. At this point, the event is available for export to the customer environment.

<ActivityItems>
 <MobileUserPropertyUpdateActivity>
  <ActivityId>UUID</ActivityId>
  <ApplicationId>SomeApplication</ApplicationId>
  <DeviceId>SomeUniqueId</DeviceId>
  <MobileAppId>1</MobileAppId>
  <MobileUserId>SomeMobileUser</MobileUserId>
  <RecipientId>SomeRecipient</RecipientId>
  <Timestamp>1970-01-01T00:00:00.002Z</Timestamp>
  <UserType>SomeUserType</UserType>
  <Attributes>{"sample1":"v1","sample2":"v2","sample3":"v3"}</Attributes>
 </MobileUserPropertyUpdateActivity>
</ActivityItems>
Element name Description
ActivityId The unique activity ID for an individual activity item.
ApplicationId The customer’s Accelerator application ID.
DeviceId The device ID from which the event/activity originated.
MobileAppId The push application from which the event/activity originated.
MobileUserId A unique user ID assigned to the user of the push app.
UserType This indicates if the user is anonymous, known, or orphaned.
RecipientId The Recipient ID for the recipient that generated an event. The Recipient ID is intended to be a unique identifier for each recipient in your source data, providing reporting metrics without the need to display PII.
Attributes A list of key value pairs that represent the properties and new values.
Timestamp The time the event/activity occurred.

Mobile application activity CSV files

MessageGears customers can export these activities in XML or CSV format.

field that contains a short name for the event. The table below illustrates the event and short name mapping.
 
Activity name Type
Mobile user first session mfsa
Mobile user session start mssa
Mobile user push permissions update mppua
Mobile user identity miua
Mobile user device update

 
Mobile user custom event

muce
Mobile user property update

mupu
Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.