NAV
shell

Overview

In a nutshell, Aampe uses the characteristics and behavior of your users to continuously personalize push notifications, i.e. decide which user receives what message and when. It then triggers those notifications at the right time and monitors their influence on long-term user behavior (End-to-end mode). Aampe can also be configured to expose personalized message content on a secured HTTP interface to be consumed on demand (Content mode; for example: to be exposed to Braze's Connected content) feature.

Integrating Aampe

The below guides walk you through the steps needed to integrate with Aampe depending on the chosen mode.

End-to-end mode

To allow Aampe to personalize and trigger push notifications, you need:

  1. Data integrations which allows Aampe to ingest your user events; and
  2. Push integrations which enables Aampe trigger push notifications on your behalf.

Content mode

To allow Aampe to personalize push notification copy and render it accessible via API, you need:

  1. Data integrations which allows Aampe to ingest your user events; and
  2. Content integrations which details the requirements so Aampe can connect to your current messaging system and still learn to personalize push notifications.

Our guides will always start with a summary of what information Aampe needs and then move to a step-by-step guide to help you provide Aampe with this information.

Data integrations

This section will guide you through the process of sharing user events and attributes with Aampe. It describes Aampe's data models and provides technical guides depending on your chosen data sharing method.

Data models

Event/transaction data

Sometimes called clickstream data, below is the data model Aampe uses to store your app events. You do not need to send the data in this precise format. Aampe will apply any needed transformations to minimize integration work on your side. This table is only provided as a reference.

Name Data Type Description
timestamp timestamp The timestamp of when the event happened in UTC
event_name string An event name following your internal naming
contact_id string A unique user identifier
event_instance_id string (Optional) An event deduplication identifier
timezone string (Optional) User timezone at the moment the event happened
metadata JSON (Optional) Any useful data points about the event (for example: product id in a added_to_cart event)

Attribute data

Static or infrequently updated user attributes can be shared separately for efficiency and will be stored using the below data model.

Name Data Type Description
contact_id string A unique user identifier
notification_token string (Optional) Push notification token, if different from contact_id
timezone string (Optional) User timezone, if not passed in event data
metadata JSON (Optional) Any useful data points about the user that you would like to use for filtering (for example: country of residence)

Some customers choose to pass those attributes with each event, and that's not a problem.

Mixpanel

A summary of the information that Aampe needs:

Aampe will essentially periodically pull from Mixpanel's RAW data export API.

Getting the Project ID and Data Residency

  1. Click on the Settings gearwheel placed at the top-right corner of your screen.
  2. Select your organization under ORGANIZATION SETTINGS.
  3. Navigate to Projects.
  4. Choose the project with the data you wish Aampe to ingest.
  5. You will find your Project ID and Data Residency in the table that will appaer.

Creating a service account

  1. Click on the Settings gearwheel placed at the top-right corner of your screen.
  2. Select your organization under ORGANIZATION SETTINGS.
  3. Navigate to Service Accounts.
  4. Click on + Add Service Account at the top-right corner.
  5. Choose a NAME for your service account. For example: aampe-data-export
  6. Select the PROJECT(S) with the data you wish Aampe to ingest.
  7. Keep the ORGANIZATION ROLE as Member and PROJECT ROLE as Consumer.
  8. Click on Create
  9. The service account Username and Secret will appear.

Segment

If you use Segment to centralize your data, the easiest way to share it with Aampe is by setting up a Google Cloud Storage Destination.

Before you begin

Aampe will provide you with:

You will need those files for step 7 below.

Configure Google Cloud Storage Destination

  1. Go to Segment’s Connection > Destinations section
    .
  2. Click on Add Destination.
  3. Search for “Google Cloud Storage” in the catalog that appears.
  4. Click on the Google Cloud Storage destination.
  5. Click on Configure Google Cloud Storage.
  6. Select the source you wish to share with Aampe and then click on Confirm Source.
  7. You will then be lead to a screen where you will provide the destination bucket details (provided by Aampe):
    • Bucket: the name of the bucket where the data will flow
    • GCS Private Key File: the content of the JSON with the access credentials to that bucket
  8. After having input both details, you need to click on the toggle that enables this destination and you are good to go!.

Amplitude

A summary of the information that Aampe needs:

Aampe will essentially pull event data from Amplitude's Export API.

Getting your API keys

  1. In your Amplitude workspace, click on Settings at the bottom left of your screen.
  2. Select Projects from the navigation bar that opens.
  3. Select the project with the events you would like Aampe to ingest.
  4. Copy your API Key and Secret Key.

CleverTap

A summary of the information that Aampe needs:

Aampe will periodically pull from CleverTap's Event API.

Create a user for Aampe

  1. Login to your CleverTap account with an admin user.
  2. Go to Setting > Users > + User to add a user.
  3. Enter developer+<your_business_name>@aampe.com in the Email field.
  4. Check the Creator role.
  5. Click on Invite.

Generating a User-Passcode for Aampe

  1. Login to your CleverTap account with an admin user.
  2. Go to Settings > Users.
  3. Pick the user you created for Aampe (See Create a user for Aampe if you haven't yet created a user).
  4. Click on the "Grant User Access" Icon at the right-side of the screen to grant a passcode to the Aampe user.
  5. Chose an infinite User Passcode TTL (Time To Live). This means that the Aampe credentials never expire to ensure continuity of service. You can always revoke or reset this passcode at your convenience.
  6. Once this is done, a developer from Aampe will be able to login and extract the User-Passcode.

Screen capture source: CleverTap developer docs

Storage buckets (S3/GCP)

If you don't use a 3rd party service to manage your event data, or you prefer that Aampe gets direct dumps from your data warehouse, you should use Aampe's bucket integration.

A general outline for a bucket integration:

  1. Create a bucket.
  2. Provide Aampe with access to that bucket.
  3. Dump event data daily, usually in JSON, ndJSON, CSV or parquet formats (we're happy to support more formats as needed).

AWS S3 - Key access

Summary: Aampe will provide you with an IAM user ARN, for which you will grant access to your bucket.

  1. Create a bucket and share its name with Aampe.
  2. Grant the IAM user created by Aampe the following permissions:

AWS S3 - Delegate access

The Aampe team will provide you with a service account subject identifier.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket_name_goes_here>",
                "arn:aws:s3:::<bucket_name_goes_here>/*"
            ]
        }
    ]
}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Federated": "accounts.google.com"
        },
        "Action": "sts:AssumeRoleWithWebIdentity",
        "Condition": {
          "StringEquals": {
            "accounts.google.com:sub": "<service_account_subject_identifier_goes_here>"
          }
        }
      }
    ]
  }

AWS S3 - Alternatives

The Aampe team is happy to help with providing alternatives if any of the above are in conflict with your IT policies. For example, Aampe can provision the bucket itself and provide an IAM role of your own access to it. All you need to do is shoot an email to developer@aampe.com

SFTP

If you don't push you event data into a 3rd party service, or you prefer that Aampe gets direct dumps from your data warehouse and you have a pipeline for pushing to FTP, we also support that.

The general steps to get this working are:

  1. Aampe provides you with SFTP credentials.
  2. You transfer event data daily, usually in JSON, ndJSON or CSV formats (we're happy to support more formats if needed).

Push integrations

AWS SNS

A summary of the information that Aampe needs:

Aampe will essentially call the AWS SNS Publish API on your behalf.

Configuring SNS for Aampe includes two steps:

  1. Create an SNS Publish policy
  2. Create an IAM user for Aampe

Create an SNS Publish policy

  1. In your AWS console, go to the Identity and Access Management (IAM) service.
  2. Select Policies in the navigation menu.
  3. Click on Create Policy
  4. Click on Choose a service
  5. Select SNS
  6. In the Actions field, type Publish then select the Publish action that appears
  7. Click on Resources, keep the Specific radio button select and tick the Any in this account checkbox
  8. Click Next: Tags and then Next: Review
  9. Choose a name for your policy, such as SNSPublish
  10. Click on Create Policy

Create an IAM user for Aampe

  1. In your AWS console, go to the Identity and Access Management (IAM) service.
  2. Select Users in the navigation menu.
  3. Click on Add users
  4. Choose a username, such as aampe-sns
  5. Tick the Access key - Programmatic access checkbox
  6. Click on Next: Permissions
  7. Click on the Attach existing policies directly button
  8. In the Search text field, type the name of the policy you created in the previous step and select it when it appears in the list under Policy name.
  9. Click on Next: Tags and Next: Review
  10. Review your choices and click on Create user
  11. You will then be lead to a success screen, from which you can copy your Access key ID and Secret access key

Braze

A summary of the information that Aampe needs:

Aampe will essentially call the Braze API for sending messages on your behalf.

Create an API key

  1. Once you are logged in to your Braze dashboard, go to Settings, and then Developer Console
  2. On this page you will find the Rest API Keys table
  3. Click on + Create New API Key
  4. Choose a name for your new key, such as aampe-push
  5. Tick the checkbox next to messages.send in the permission list
  6. Finalize the key creation.
  7. You can then view the newly created key by clicking on the gear icon at the right
  8. Copy the API key value

Screen capture source: The Braze developer docs.

CleverTap

A summary of the information that Aampe needs:

Aampe will essentially call CleverTap's Campaign API on your behalf.

Create a user for Aampe

  1. Login to your CleverTap account with an admin user.
  2. Go to Setting > Users > + User to add a user.
  3. Enter developer+<your_business_name>@aampe.com in the Email field.
  4. Check the Creator role.
  5. Click on Invite.

Generating a User-Passcode

  1. Login to your CleverTap account with an admin user.
  2. Go to Settings > Users.
  3. Pick the user you created for Aampe (See Create a user for Aampe if you haven't created a user yet).
  4. Click on the Grant User Access Icon at the right-side of the screen to grant a passcode to the Aampe user.
  5. Chose an infinite User Passcode TTL (Time To Live). This means that the Aampe credentials never expire to ensure continuity of service. You can always revoke or reset this passcode at will.
  6. Once this is done, a developer from Aampe will be able to login and extract the User-Passcode.

Screen capture source: CleverTap developer docs.

Firebase Cloud Messaging

A summary of the information that Aampe needs:

Aampe will essentially call the Firebase Cloud Messaging API on your behalf.

Setting up Firebase Cloud Messages involves four steps:

  1. Enable the Cloud Messaging API
  2. Create a custom role for message creation
  3. Create a service account
  4. Generate a key

Enable the Cloud Messaging API

  1. Type "Firebase Cloud Messaging API" in the Search products and resources textbox.
  2. Choose Firebase Cloud Messaging API from the list.
  3. Click on the blue Enable button.

Create a custom role for message creation

A custom Role must be created in the system to allow Aampe to trigger notifications using the API because the default roles do not provide granular enough permissions.

  1. Type "Roles" in the Search products and resources textbox and select the Roles (IAM and Admin) option. This will take you to the Roles page.
  2. Click on + CREATE ROLE
  3. Fill in the role Title, Description and ID according to your conventions.
  4. Click on +ADD PERMISSIONS
  5. In the window that opens, search for cloudmessaging.messages.create using the textbox to the right of the Filter and select the cloudmessaging.messages.create entry that appears.
  6. Tick the cloudmessaging.messages.create permission and click on ADD
  7. Once added, click on CREATE to complete the role creation.

Create a service account

  1. Type "Service accounts" in the Search products and resources textbox.
  2. Choose Service accounts (IAM and admin) from the list. This will take you to the service account page.
  3. Click on + CREATE SERVICE ACCOUNT
  4. Fill in the Service account name, ID and description according to your conventions.
  5. Click on CREATE AND CONTINUE
  6. On the Grant this service account access to the project screen, click on the Select a role dropdown.
  7. Under Quick access > Custom, select the custom role you created in the previous step.
  8. Click on + ADD ANOTHER ROLE and then on the Select a role dropdown.
  9. Type "Firebase Cloud Messaging Admin" in the box near the Filter.
  10. Select the suggested Firebase Cloud Messaging Admin role.
  11. Click on DONE to complete the service account creation.

Generate a kay

  1. In your "Service accounts" page, find the service account you created for Aampe and click on the three dots in the Actions column and select Manage keys
  2. Click on ADD KEY and select Create new key
  3. Select the JSON Key type and click on CREATE
  4. Your browser will download a .json file with the key needed by Aampe.

MoEngage

A summary of the information that Aampe needs:

Aampe will essentially call the MoEngage Push API on your behalf.

OneSignal

A summary of the information that Aampe needs:

Aampe will essentially call the OneSignal API on your behalf.

Getting your App ID and API Key

  1. Once logged in to OneSignal, select the application you want to integrate with Aampe
  2. Select Settings from the navigation bar at the top of the screen.
  3. Select Keys & IDs from the sub-navigation bar that opens.
  4. Copy the OneSignal App ID and Rest API Key.

Salesforce Marketing Cloud

Documentation will be added soon.

Custom APIs

If you've build a custom solution for pushing notifications, team Aampe will be glad to integrate with it for your convenience. All you need to do is shoot an email to developer@aampe.com attaching the API spec.

Content integrations

Braze

Aampe-personalized message content via Braze's Connected Content feature.

Usage example

When creating a message in Braze, you will copy/paste a snippet to the one on the right from the Aampe Composer to the Braze UI. Then, you will use message_content as a Liquid variable in the construction of the message.

{% connected_content https://aam.pe/message_content?canvas_id={'{{canvas.${name}'}&contact_id={'{{${user_id}}}'} :basic_auth aampe :save message_content :retry %}

message_content will contain the header & body keys that provide the personalized push notification along with an assignment_id to be propagated as a notification event metadata field (see requirements below).

Requirements