User Guides
Send custom events to Airship¶
Airship Custom Events send behavioral events from Amperity to Airship, where each event can trigger an Airship automation — such as a push notification, in-app message, SMS, or email — and personalize the message it sends. Airship is a customer engagement platform that helps marketers connect with their customers across every stage of the customer lifecycle.
Send custom events to Airship so that customer behavior in Amperity can trigger an Airship automation — such as a push notification, in-app message, SMS, or email — and personalize the message it sends. Each row returned by your query is sent as a single Airship custom event, carrying an event name, a customer identifier, an optional timestamp, and any additional columns as event properties.
An event is different from a profile attribute: an Airship automation listens for an event by name and acts when it arrives, whereas attributes only enrich a profile for segmentation and personalization. This connector sends events; the Airship Attributes connector sends attributes. Unlike the file-based Airship connector, which delivers a file to an Airship SFTP location, this connector sends events to Airship directly.
Amperity sends customer identifiers to Airship exactly as your query returns them. Unlike some event connectors, this connector does not hash or normalize identifiers, so provide values in the form Airship expects.
Note
Amperity provides three separate Airship connectors, each with its own credentials: Airship Custom Events (this connector) sends behavioral events; Airship Attributes sends profile attributes; and Airship sends files to an Airship SFTP location. Set up each connector you use separately.
Beta
The Airship Custom Events connector is currently in beta. Contact your Amperity representative to learn more.
Build a query¶
Use a query to build a combination of data that returns one row per event to send to Airship. Each row must include a customer identifier and an event name; you can also include a timestamp and any additional columns, which are sent as event properties that an Airship automation can read to personalize its message.
Review the Event fields section for the columns your query must and may return, and the Identifier types section for the allowed Identifier type values.
Identifier types¶
The Identifier type setting names which kind of Airship identifier the airship_identifier column holds. Airship requires exactly one identifier per event, so this single choice applies to the whole orchestration. The supported values are:
named_user_id — an Airship named user ID. Limited to 128 characters.
channel — a generic Airship channel.
ios_channel, android_channel, amazon_channel, web_channel — a channel for a specific platform.
Every value other than named_user_id must be a valid Airship channel UUID. sms_channel, email_channel, and open_channel are not supported for events even though Airship accepts them for some static list uploads, so an event cannot be keyed on an email address or phone number.
Add orchestration¶
An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.
To add an orchestration
Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.
From the Object type dropdown, select Query.
From the Object dropdown, select the query for which results is sent to Airship.
From the Destination dropdown, select a destination that is configured for sending data to Airship.
Verify all settings.
Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.
Click Save.
Run orchestration¶
Run the orchestration manually to validate that it works.
To run the orchestration
Open the Activations page, select the Orchestrations tab, and then open the menu for the Airship orchestration. Select Run.
The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.
When the orchestration has run successfully, the status is updated to “Completed”.
Data validation¶
Airship validates a batch of events all or nothing: one event it rejects causes the entire batch to be rejected, and no event in that batch is applied. To prevent one bad row from discarding the rest, Amperity validates each row before sending and holds back rows that Airship would reject. Held-back rows are reported as failed with the reason, and the remaining rows are sent. A row is held back when:
airship_identifier is missing.
Identifier type is named_user_id and the identifier is longer than 128 characters.
Identifier type is a channel type and the identifier is not a valid UUID.
event_name is missing, or is longer than 255 characters.
occurred is present but cannot be read as a timestamp, is more than three months old, or is more than one hour in the future.
interaction_id or interaction_type is longer than 255 characters.
The event’s properties serialize to more than 65,536 bytes (64 KB).
Event fields¶
The following table describes each column Amperity sends to Airship. A query must return columns with the same name as listed in the “Amperity name” column.
Important
A query must return airship_identifier and event_name. All other columns are optional.
Amperity name |
Airship field |
Description |
|---|---|---|
airship_identifier |
user |
Required The customer identifier the event is attached to. The Identifier type setting determines which kind of Airship identifier this is. A named user ID is limited to 128 characters; every channel type must be a valid channel UUID. Sent as returned by your query — not hashed or normalized. |
event_name |
body.name |
Required The name of the event, which is what an Airship automation listens for. Amperity lower-cases the value before sending, because Airship rejects any name containing an uppercase character; spaces, dots, hyphens, leading digits, and non-English characters are all accepted. Limited to 255 characters. Note Airship accepts an event name that no automation listens for and silently does nothing with it. Confirm the exact event names your Airship automations expect, and remember that the automation name must be lower case to match. |
occurred |
occurred |
Optional When the event occurred. Send a full ISO 8601 timestamp that includes a time — for example, |
interaction_id |
body.interaction_id |
Optional An interaction identifier carried on the event body. Limited to 255 characters. Important Send interaction_id and interaction_type under exactly these column names. A property with any other name — including a spelling Airship does not recognize — is accepted and stored as an ordinary property, where Airship reporting cannot find it. The mismatch is invisible at send time and shows up later as missing values in reporting. |
interaction_type |
body.interaction_type |
Optional An interaction type carried on the event body. Limited to 255 characters. |
Any other column |
body.properties.<column> |
Optional Every column that is not one of the fields above is sent as an event property, keyed by the column name. Properties are what Airship message templating reads, so use them to personalize the message an event triggers. Columns with a blank value are dropped rather than sent as empty properties, and all properties together must serialize to no more than 65,536 bytes (64 KB). Note Airship treats value, transaction, and session_id specially in its own API, but this connector does not: a column with one of those names is sent as an ordinary property, not on the event body. |