Track segment membership changes in Connect Customer

You can subscribe a segment to receive notifications whenever the membership of the segment changes. A membership change occurs when a customer profile enters or exits the segment based on the segment criteria. This can happen because of a change in a profile, an associated object, or a calculated attribute. Membership changes are determined in two ways:

Customer Profiles sends both types of notification to the Amazon Kinesis data stream that you configure for segment membership changes, using the IAM role that you provide.

Set up segment membership streaming

Enabling segment membership streaming is a one-time setup that an administrator performs for the domain. It sets the destination Kinesis data stream that membership events are delivered to. Enabling the stream does not enable membership events by default — you must also subscribe individual segments to receive notifications, and the same Kinesis data stream is shared across all subscribed segments in the domain.

When you enable segment membership streaming, Customer Profiles assumes the role that you specify. Because of this, the IAM principal that enables streaming must have permission to pass that role to Customer Profiles. Grant the iam:PassRole action for the Kinesis role to the principal, scoped to the Customer Profiles service. The following is a sample statement to add to the principal's permissions.

{
    "Effect": "Allow",
    "Action": "iam:PassRole",
    "Resource": "arn:aws:iam::123456789012:role/my-segment-events-role",
    "Condition": {
        "StringEquals": {
            "iam:PassedToService": "profile.amazonaws.com"
        }
    }
}
                

The IAM role that you provide must trust the Customer Profiles service principal and grant permissions to write to the Kinesis data stream. The following is a sample trust policy for the Kinesis role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "profile.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
                

The following is a sample of the permissions to grant the Kinesis role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kinesis:PutRecord",
                "kinesis:PutRecords",
                "kinesis:DescribeStream"
            ],
            "Resource": "arn:aws:kinesis:us-west-2:123456789012:stream/my-segment-events-stream"
        }
    ]
}
                

If your Kinesis data stream is encrypted with a customer managed AWS KMS key, the role also needs permission to use that key to write to the stream. Add the following statement, scoped to your AWS KMS key, to the role's permissions.

{
    "Effect": "Allow",
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-123456SAMPLE"
}
                

Key concepts

The following terms are important for understanding segment membership events.

Enable and view events

After a segment is created, you can enable the subscription from the Connect Customer admin website by choosing Track membership changes.

After you enable tracking, Customer Profiles sends notifications to the Kinesis data stream associated with segment membership changes. If your administrator has not configured a stream, a message prompts you to enable segment membership streaming first.

After tracking is enabled, you see messages that provide detail about the initial snapshot.

Viewing events

Events are published to the Kinesis data stream in your account. After the initial snapshot completes, you can also view streaming events from the same section, and you can view membership event details on individual profiles. There might be a delay between when a membership change occurs and when it appears in the list of streaming events.

Stop tracking changes

If you no longer want to receive notifications, choose Stop tracking changes.

CloudWatch metrics

You can view CloudWatch metrics for your segment membership events under your domain and segment. The following metrics are available.

Segment membership changes payload

Customer Profiles sends this event to your Kinesis data stream each time a customer profile enters or exits a segment. The following is a sample segment membership event in JSON.

{
    "AccountId": "123456789012",
    "DomainName": "cp-domain-prod",
    "SegmentDefinitionName": "PeopleInSeattle",
    "SegmentType": "CLASSIC",
    "ProfileId": "0d25b61368c64fb786347d7e7314c6f1",
    "OperationType": "JOINED",
    "MembershipCalculatedAt": 1773967675,
    "PreviousMembershipChangedAt": 1773965432,
    "EventType": "LIVE"
}
                

The following list describes the fields in the segment membership event payload.