Amazon Pinpoint
User Guide

Importing Segments

With Amazon Pinpoint, you can define a user segment by importing a file that contains information about the users who belong to the segment. Importing segments is useful if you define user segments outside of Amazon Pinpoint but you want to engage your users with Amazon Pinpoint campaigns.

Unlike the dynamic segments that you create with the segment builder in the console, an imported segment is an unchanging set of endpoints or user IDs:

Endpoint

A destination that you can send messages to, such as an email address, mobile device identifier, or mobile phone number. An endpoint definition can include attributes that describe the user or device that you send messages to. It can also include a user ID.

You can define a segment by importing a list of endpoint definitions. Amazon Pinpoint creates the segment, and it updates any endpoints that you previously added to Amazon Pinpoint with the new information.

User ID

An ID that represents an individual user in your audience. This ID must be assigned to one or more endpoints. For example, if a person uses your app on more than one device, your app could assign that person's user ID to the endpoint for each device.

You can define a segment by importing user IDs only if you've added the endpoints that are associated with the user IDs to Amazon Pinpoint.

An imported segment consists of endpoints, user IDs, or a combination of both. When you use Amazon Pinpoint to send a message to the segment, the potential destinations include:

  • Each endpoint that you list in the imported file.

  • Each endpoint that's associated with each user ID that you list in the imported file.

When you create a new segment, you can use an imported segment as the base segment. You can then apply filters to the base segment to refine it according to your needs.

Imported Segment Considerations

Consider the following factors when you create imported segments:

  • When you create a campaign, you have to choose a segment. When you choose a dynamic segment, Amazon Pinpoint provides an estimate of the size of that segment. However, when you choose an imported segment, Amazon Pinpoint can't provide an estimate.

  • If you create a campaign that sends messages when certain events happen, you can't use imported segments. Event-based campaigns can only use dynamic segments. For more information about creating dynamic segments, see Building Segments.

Segment Files

You define the endpoints or user IDs that belong to your segment in a comma-separated values (CSV) or JSON file. Then, you import the file into Amazon Pinpoint to create the segment.

When you import a segment, remember the following:

  • Amazon Pinpoint can't import compressed files.

  • The files that you import must use UTF-8 character encoding.

  • If you're importing new endpoints, the Address and ChannelType attributes are required.

  • If you're updating existing endpoints, the Id attribute is required for each endpoint that you want to update.

  • Your endpoint definitions can include only certain attributes. For a list, see Available Attributes.

Example Segment Files

The example files in this section are based on the following data:

Example Endpoint Attribute Values

ChannelType Address Location.Country Demographic.Platform Demographic.Make User.UserId
SMS +12365550182 CAN Android LG example-user-id-1
APNS 1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f USA iOS Apple example-user-id-2
EMAIL john.stiles@example.com USA iOS Apple example-user-id-2
GCM 4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c CHN Android Google example-user-id-3
EMAIL wang.xiulan@example.com CHN Android OnePlus example-user-id-3

Each row in this table represents an individual endpoint. Note that the user IDs example-user-id-2 and example-user-id-3 are assigned to two endpoints each.

Example File with Endpoint Definitions

CSVJSON
CSV

You can import endpoints that are defined in a CSV file, as in the following example:

ChannelType,Address,Location.Country,Demographic.Platform,Demographic.Make,User.UserId SMS,2065550182,CAN,Android,LG,example-user-id-1 APNS,1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f,USA,iOS,Apple,example-user-id-2 EMAIL,john.stiles@example.com,USA,iOS,Apple,example-user-id-2 GCM,4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c,CHN,Android,Google,example-user-id-3 EMAIL,wang.xiulan@example.com,CHN,Android,OnePlus,example-user-id-3

The first line is the header, which contains the endpoint attributes. For the supported attributes, see Available Attributes.

The subsequent lines define the endpoints by providing values for each attribute in the header.

To include a comma, line break, or double quote in a value, enclose the value in double quotes, as in "aaa,bbb". For more information about the CSV format, see RFC 4180 Common Format and MIME Type for Comma-Separated Values (CSV) Files.

JSON

You can import endpoints that are defined in a newline-delimited JSON file. In this format, each line is a complete JSON object that contains an individual endpoint definition, as in the following example:

{"ChannelType":"SMS","Address":"2065550182","Location":{"Country":"CAN"},"Demographic":{"Platform":"Android","Make":"LG"},"User":{"UserId":"example-user-id-1"}} {"ChannelType":"APNS","Address":"1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f","Location":{"Country":"USA"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}} {"ChannelType":"EMAIL","Address":"john.stiles@example.com","Location":{"Country":"USA"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}} {"ChannelType":"GCM","Address":"4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c","Location":{"Country":"CHN"},"Demographic":{"Platform":"Android","Make":"Google"},"User":{"UserId":"example-user-id-3"}} {"ChannelType":"EMAIL","Address":"wang.xiulan@example.com","Location":{"Country":"CHN"},"Demographic":{"Platform":"Android","Make":"OnePlus"},"User":{"UserId":"example-user-id-3"}}

For the supported attributes, see Available Attributes.

Example File with User IDs

CSVJSON
CSV

You can also import user IDs that are listed in a CSV file, as in the following example:

User.UserId example-user-id-1 example-user-id-2 example-user-id-3

The first line is the header, which must contain only the User.UserId attribute.

The subsequent lines list each user ID that belongs to the segment.

As you can see in the example endpoint definitions, the user ID example-user-id-1 is associated with one endpoint. The user IDs example-user-id-2 and example-user-id-3 are associated with two endpoints each. Therefore, the segment that's created by importing this file could be used to message up to five endpoints.

JSON

You can also import user IDs that are listed in a newline-delimited JSON file, as in the following example:

{"User":{"UserId":"example-user-id-1"}} {"User":{"UserId":"example-user-id-2"}} {"User":{"UserId":"example-user-id-3"}}

As you can see in the example endpoint definitions, the user ID example-user-id-1 is associated with one endpoint. The user IDs example-user-id-2 and example-user-id-3 are associated with two endpoints each. Therefore, the segment that's created by importing this file could be used to message up to five endpoints.

Importing a Segment

There are two ways to import segments into Amazon Pinpoint: you can upload files directly from your computer, or you can import files that are stored in an Amazon S3 bucket.

Uploading files from your computer is generally the easier method of importing segments, especially if you already have the customer data on your computer. However, you can only import 10 files at a time, and you can only upload files that are smaller than 1 gigabyte (GB).

If you need to import more than 10 files at one time, or if you need to upload files that are larger than 1 GB, then you should import files from Amazon S3. The Amazon S3 import option is also useful if you already have processes that send customer data files to Amazon S3 for storage.

This section includes procedures for importing segments by using both of these methods.

Importing a Segment by Uploading a File From Your Computer

You can create segments by uploading up to 10 files directly from your computer. The files that you upload can be in CSV or JSON format. You can upload files in any combination of formats. For example, you can upload one JSON file and three CSV files.

To import a segment

  1. Open the Amazon Pinpoint console at https://console.aws.amazon.com/pinpoint/.

  2. On the All projects page, choose the project that you want to add the segment to.

  3. In the navigation pane, choose Segments.

  4. Choose Create a segment.

  5. Under Create a segment, choose Import a segment.

  6. Under Import method, choose Upload files from your computer.

  7. Under Files to import, select Choose files. Select the file or files that you want to import.

    Note

    You can also drag files from your computer's file explorer and drop them directly on the Drop files here area.

  8. When you upload files to Amazon Pinpoint, you have to provide a segment name for each file that you import. Under Segment names, enter a segment name for each file that you want to import, as shown in the following image.

    
                                An image that shows the Segment names section on the segment
                                    creation page. In this example, the user has uploaded two files:
                                        High Value Customers.csv and
                                        Top Users by Activity.json. By default,
                                    Amazon Pinpoint gives each segment a name that is equal to the file name,
                                    without the file extension.

    Note

    By default, Amazon Pinpoint provides a segment name that is equal to the name of the imported file, but without the file extension. You can change these default values to any name.

    You can use the same name for multiple segments. If you do, Amazon Pinpoint creates a distinct segment for each file, and assigns a unique ID to each file. The creation date is also slightly different for each file that you import. You can use these factors to distinguish between segments that have the same name.

  9. When you finish, choose Create segment.

Importing a Segment From a File Stored in Amazon S3

Before you use this procedure to import a segment, you first have to create an Amazon S3 bucket and upload your file to that bucket. You can organize the files for different segments into separate folders. When Amazon Pinpoint imports the endpoints or user IDs for a segment, it includes the files within all folders and subfolders that belong to the Amazon S3 location you specify.

For an introduction to creating buckets and uploading objects, see the Amazon Simple Storage Service Getting Started Guide.

Amazon Pinpoint can import only one file format (CSV or JSON) per segment, so the Amazon S3 path that you specify should only contain files of a single type.

To import a segment

  1. Open the Amazon Pinpoint console at https://console.aws.amazon.com/pinpoint/.

  2. On the All projects page, choose the project that you want to add the segment to.

  3. In the navigation pane, choose Segments.

  4. Choose Create a segment.

  5. Under Create a segment, choose Import a segment.

  6. For Segment name, enter a name for your segment to make it easy to recognize later.

  7. For Amazon S3 URL, enter the location of the Amazon S3 bucket that contains the file for your segment. The address of the bucket must be in the following format:

    s3://bucket-name/folder-name

    Amazon Pinpoint imports the files from the path that you specify, and from any subfolders in that path.

  8. For IAM role, complete one of the following steps:

    • If you want to have Amazon Pinpoint create a role that allows it to read from an Amazon S3 bucket, choose Automatically create a role. Then, for IAM role, enter a name for the role that you're creating.

    • If you've already created an IAM role that allows Amazon Pinpoint to read from an Amazon S3 bucket, choose Choose an existing role. Then, for IAM role, choose a role that contains the appropriate permissions.

    If you want to create the IAM role yourself, see IAM Role for Importing Endpoints or Segments in the Amazon Pinpoint Developer Guide. After you create the role, specify it in the Amazon Pinpoint console.

  9. Under What type of file are you importing, choose either JavaScript Object Notation (JSON) or Comma-Separated Values (CSV), depending on the format the file that you uploaded to Amazon S3.

  10. Choose Create segment.

Available Attributes

The table in this section provides the attributes that you can specify in the endpoint definitions that you import into Amazon Pinpoint. If you import segments by using CSV files, the headers in the file should match the names shown in the Attributes column.

For JSON files, a period in the attribute name indicates that the name following the period is an object that's nested in a parent object with a name equal to the value preceding the period. For example, a JSON file that contains the Demographic.Make and Demographic.Model attributes has the following structure:

{ ... "Demographic": { ... "Make":"Apple", "Model":"iPhone" ... } ... }

The full JSON structure closely resembles the example Endpoint request in the Amazon Pinpoint API Reference. However, not all attributes in the Endpoint request schema are supported when you import segments, including EndpointStatus and EffectiveDate.

You can replace attribute names that are shown in italics with any value. For example, you can create custom attributes called User.UserAttributes.FirstName and User.UserAttributes.LastName.

Attribute Description
Address The unique destination of the endpoint, such as an email address, a mobile phone number, or a token for push notifications.
Attributes.custom_attribute Custom attributes that your app reports to Amazon Pinpoint. You can use these attributes as selection criteria when you create a segment. You can replace custom_attribute with any value. You can specify up to 20 custom attributes per endpoint.
ChannelType The channel type of the endpoint. Acceptable values are:
  • APNS – For an endpoint that can receive push notifications from the Apple Push Notification service (APNs).

  • EMAIL – For an endpoint that can receive email messages.

  • GCM – For an endpoint that can receive push notifications from the Firebase Cloud Messaging (FCM) service, formerly the Google Cloud Messaging (GCM) service.

  • SMS – For an endpoint that can receive SMS text messages.

Demographic.AppVersion The version number of the application that's associated with the endpoint.
Demographic.Locale The locale of the endpoint in ISO 15897 format. For example, en_US (English language locale for the United States) or zh_CN (Chinese locale for China).
Demographic.Make The manufacturer of the endpoint device, such as Apple or Samsung.
Demographic.Model The model of the endpoint device, such as iPhone.
Demographic.ModelVersion The model version of the endpoint device.
Demographic.Platform The operating system of the endpoint device, such as ios or android.
Demographic.PlatformVersion The platform version of the endpoint device.
Demographic.Timezone The time zone of the endpoint. It's specified as a tz database value, such as America/Los_Angeles.
EffectiveDate The time when the endpoint was last updated, in ISO 8601 format. For example, 20171011T150548Z.
Id The unique ID of the endpoint.
Location.City The city where the endpoint is located.
Location.Country The three-letter code for the country or region where the endpoint is located, in ISO 3166-1 alpha-3 format. For example, USA (United States) or CHN (China). For a complete list of ISO 3166-1 alpha-3 abbreviations, see the ISO website.
Location.Latitude The latitude coordinate of the endpoint location, rounded to one decimal place.
Location.Longitude The longitude coordinate of the endpoint location, rounded to one decimal place.
Location.PostalCode The postal or ZIP code of the endpoint.
Location.Region The region of the endpoint location, such as a state or province.
Metrics.custom_attribute Custom metrics, such as the number of sessions or number of items left in a cart, to use for segmentation purposes. You can replace custom_attribute with any value. You can specify up to 20 custom attributes per endpoint.

These custom values can only be numeric. Because they're numeric, Amazon Pinpoint can perform arithmetic operations, such as the average or sum, on them.

OptOut Indicates whether a user has opted out of receiving messages. Acceptable values are: ALL (the user has opted out of all messages) or NONE (the user hasn't opted out and receives all messages).
RequestId The unique ID of the most recent request to update the endpoint.
User.UserAttributes.custom_attribute Custom attributes that are specific to the user. You can replace custom_attribute with any value, such as FirstName or Age. You can specify up to 20 custom attributes per endpoint.
User.UserId The unique ID of the user.

Note

You can specify up to 20 custom attributes per endpoint for Attributes, Metrics, and User.UserAttributes. However, you can create no more than 40 custom attributes per AWS account.