REST Resource: properties.audiences

Resource: Audience

A resource message representing a GA4 Audience.

JSON representation 
{
  "name": string,
  "displayName": string,
  "description": string,
  "membershipDurationDays": integer,
  "adsPersonalizationEnabled": boolean,
  "eventTrigger": {
    object (AudienceEventTrigger)
  },
  "exclusionDurationMode": enum (AudienceExclusionDurationMode),
  "filterClauses": [
    {
      object (AudienceFilterClause)
    }
  ],
  "createTime": string
}
Fields
name

string

Output only. The resource name for this Audience resource. Format: properties/{propertyId}/audiences/{audienceId}
displayName

string

Required. The display name of the Audience.
description

string

Required. The description of the Audience.
membershipDurationDays

integer

Required. Immutable. The duration a user should stay in an Audience. It cannot be set to more than 540 days.
adsPersonalizationEnabled

boolean

Output only. It is automatically set by GA to false if this is an NPA Audience and is excluded from ads personalization.
eventTrigger

object (AudienceEventTrigger)

Optional. Specifies an event to log when a user joins the Audience. If not set, no event is logged when a user joins the Audience.
exclusionDurationMode

enum (AudienceExclusionDurationMode)

Immutable. Specifies how long an exclusion lasts for users that meet the exclusion filter. It is applied to all EXCLUDE filter clauses and is ignored when there is no EXCLUDE filter clause in the Audience.
filterClauses[]

object (AudienceFilterClause)

Required. Immutable. Unordered list. Filter clauses that define the Audience. All clauses will be AND’ed together.
createTime

string (Timestamp format)

Output only. Time when the Audience was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

AudienceEventTrigger

Specifies an event to log when a user joins the Audience.

JSON representation 
{
  "eventName": string,
  "logCondition": enum (LogCondition)
}
Fields
eventName

string

Required. The event name that will be logged.
logCondition

enum (LogCondition)

Required. When to log the event.

LogCondition

Determines when to log the event.

Enums
LOG_CONDITION_UNSPECIFIED Log condition is not specified.
AUDIENCE_JOINED The event should be logged only when a user is joined.
AUDIENCE_MEMBERSHIP_RENEWED The event should be logged whenever the Audience condition is met, even if the user is already a member of the Audience.

AudienceExclusionDurationMode

Specifies how long an exclusion lasts for users that meet the exclusion filter.

Enums
AUDIENCE_EXCLUSION_DURATION_MODE_UNSPECIFIED Not specified.
EXCLUDE_TEMPORARILY Exclude users from the Audience during periods when they meet the filter clause.
EXCLUDE_PERMANENTLY Exclude users from the Audience if they've ever met the filter clause.

AudienceFilterClause

A clause for defining either a simple or sequence filter. A filter can be inclusive (For example, users satisfying the filter clause are included in the Audience) or exclusive (For example, users satisfying the filter clause are excluded from the Audience).

JSON representation 
{
  "clauseType": enum (AudienceClauseType),

  // Union field filter can be only one of the following:
  "simpleFilter": {
    object (AudienceSimpleFilter)
  },
  "sequenceFilter": {
    object (AudienceSequenceFilter)
  }
  // End of list of possible types for union field filter.
}
Fields
clauseType

enum (AudienceClauseType)

Required. Specifies whether this is an include or exclude filter clause.

Union field filter.

filter can be only one of the following:
simpleFilter

object (AudienceSimpleFilter)

A simple filter that a user must satisfy to be a member of the Audience.
sequenceFilter

object (AudienceSequenceFilter)

Filters that must occur in a specific order for the user to be a member of the Audience.

AudienceSimpleFilter

Defines a simple filter that a user must satisfy to be a member of the Audience.

JSON representation 
{
  "scope": enum (AudienceFilterScope),
  "filterExpression": {
    object (AudienceFilterExpression)
  }
}
Fields
scope

enum (AudienceFilterScope)

Required. Immutable. Specifies the scope for this filter.
filterExpression

object (AudienceFilterExpression)

Required. Immutable. A logical expression of Audience dimension, metric, or event filters.

AudienceFilterScope

Specifies how to evaluate users for joining an Audience.

Enums
AUDIENCE_FILTER_SCOPE_UNSPECIFIED Scope is not specified.
AUDIENCE_FILTER_SCOPE_WITHIN_SAME_EVENT User joins the Audience if the filter condition is met within one event.
AUDIENCE_FILTER_SCOPE_WITHIN_SAME_SESSION User joins the Audience if the filter condition is met within one session.
AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS User joins the Audience if the filter condition is met by any event across any session.

AudienceFilterExpression

A logical expression of Audience dimension, metric, or event filters.

JSON representation 
{

  // Union field expr can be only one of the following:
  "andGroup": {
    object (AudienceFilterExpressionList)
  },
  "orGroup": {
    object (AudienceFilterExpressionList)
  },
  "notExpression": {
    object (AudienceFilterExpression)
  },
  "dimensionOrMetricFilter": {
    object (AudienceDimensionOrMetricFilter)
  },
  "eventFilter": {
    object (AudienceEventFilter)
  }
  // End of list of possible types for union field expr.
}
Fields
Union field expr. The expression applied to a filter. expr can be only one of the following:
andGroup

object (AudienceFilterExpressionList)

A list of expressions to be AND’ed together. It can only contain AudienceFilterExpressions with orGroup. This must be set for the top level AudienceFilterExpression.
orGroup

object (AudienceFilterExpressionList)

A list of expressions to OR’ed together. It cannot contain AudienceFilterExpressions with andGroup or orGroup.
notExpression

object (AudienceFilterExpression)

A filter expression to be NOT'ed (For example, inverted, complemented). It can only include a dimensionOrMetricFilter. This cannot be set on the top level AudienceFilterExpression.
dimensionOrMetricFilter

object (AudienceDimensionOrMetricFilter)

A filter on a single dimension or metric. This cannot be set on the top level AudienceFilterExpression.
eventFilter

object (AudienceEventFilter)

Creates a filter that matches a specific event. This cannot be set on the top level AudienceFilterExpression.

AudienceFilterExpressionList

A list of Audience filter expressions.

JSON representation 
{
  "filterExpressions": [
    {
      object (AudienceFilterExpression)
    }
  ]
}
Fields
filterExpressions[]

object (AudienceFilterExpression)

A list of Audience filter expressions.

AudienceDimensionOrMetricFilter

A specific filter for a single dimension or metric.

JSON representation 
{
  "fieldName": string,
  "atAnyPointInTime": boolean,
  "inAnyNDayPeriod": integer,

  // Union field one_filter can be only one of the following:
  "stringFilter": {
    object (StringFilter)
  },
  "inListFilter": {
    object (InListFilter)
  },
  "numericFilter": {
    object (NumericFilter)
  },
  "betweenFilter": {
    object (BetweenFilter)
  }
  // End of list of possible types for union field one_filter.
}
Fields
fieldName

string

Required. Immutable. The dimension name or metric name to filter. If the field name refers to a custom dimension or metric, a scope prefix will be added to the front of the custom dimensions or metric name. For more on scope prefixes or custom dimensions/metrics, reference the Google Analytics Data API documentation.
atAnyPointInTime

boolean

Optional. Indicates whether this filter needs dynamic evaluation or not. If set to true, users join the Audience if they ever met the condition (static evaluation). If unset or set to false, user evaluation for an Audience is dynamic; users are added to an Audience when they meet the conditions and then removed when they no longer meet them.

This can only be set when Audience scope is ACROSS_ALL_SESSIONS.
inAnyNDayPeriod

integer

Optional. If set, specifies the time window for which to evaluate data in number of days. If not set, then audience data is evaluated against lifetime data (For example, infinite time window).

For example, if set to 1 day, only the current day's data is evaluated. The reference point is the current day when atAnyPointInTime is unset or false.

It can only be set when Audience scope is ACROSS_ALL_SESSIONS and cannot be greater than 60 days.
Union field one_filter. One of the above filters. one_filter can be only one of the following:
stringFilter

object (StringFilter)

A filter for a string-type dimension that matches a particular pattern.
inListFilter

object (InListFilter)

A filter for a string dimension that matches a particular list of options.
numericFilter

object (NumericFilter)

A filter for numeric or date values on a dimension or metric.
betweenFilter

object (BetweenFilter)

A filter for numeric or date values between certain values on a dimension or metric.

StringFilter

A filter for a string-type dimension that matches a particular pattern.

JSON representation 
{
  "matchType": enum (MatchType),
  "value": string,
  "caseSensitive": boolean
}
Fields
matchType

enum (MatchType)

Required. The match type for the string filter.
value

string

Required. The string value to be matched against.
caseSensitive

boolean

Optional. If true, the match is case-sensitive. If false, the match is case-insensitive.

MatchType

The match type for the string filter.

Enums
MATCH_TYPE_UNSPECIFIED Unspecified
EXACT Exact match of the string value.
BEGINS_WITH Begins with the string value.
ENDS_WITH Ends with the string value.
CONTAINS Contains the string value.
FULL_REGEXP Full regular expression matches with the string value.

InListFilter

A filter for a string dimension that matches a particular list of options.

JSON representation 
{
  "values": [
    string
  ],
  "caseSensitive": boolean
}
Fields
values[]

string

Required. The list of possible string values to match against. Must be non-empty.
caseSensitive

boolean

Optional. If true, the match is case-sensitive. If false, the match is case-insensitive.

NumericFilter

A filter for numeric or date values on a dimension or metric.

JSON representation 
{
  "operation": enum (Operation),
  "value": {
    object (NumericValue)
  }
}
Fields
operation

enum (Operation)

Required. The operation applied to a numeric filter.
value

object (NumericValue)

Required. The numeric or date value to match against.

Operation

The operation applied to a numeric filter.

Enums
OPERATION_UNSPECIFIED Unspecified.
EQUAL Equal.
LESS_THAN Less than.
GREATER_THAN Greater than.

NumericValue

To represent a number.

JSON representation 
{

  // Union field one_value can be only one of the following:
  "int64Value": string,
  "doubleValue": number
  // End of list of possible types for union field one_value.
}
Fields
Union field one_value. One of a numeric value. one_value can be only one of the following:
int64Value

string (int64 format)

Integer value.
doubleValue

number

Double value.

BetweenFilter

A filter for numeric or date values between certain values on a dimension or metric.

JSON representation 
{
  "fromValue": {
    object (NumericValue)
  },
  "toValue": {
    object (NumericValue)
  }
}
Fields
fromValue

object (NumericValue)

Required. Begins with this number, inclusive.
toValue

object (NumericValue)

Required. Ends with this number, inclusive.

AudienceEventFilter

A filter that matches events of a single event name. If an event parameter is specified, only the subset of events that match both the single event name and the parameter filter expressions match this event filter.

JSON representation 
{
  "eventName": string,
  "eventParameterFilterExpression": {
    object (AudienceFilterExpression)
  }
}
Fields
eventName

string

Required. Immutable. The name of the event to match against.
eventParameterFilterExpression

object (AudienceFilterExpression)

Optional. If specified, this filter matches events that match both the single event name and the parameter filter expressions. AudienceEventFilter inside the parameter filter expression cannot be set (For example, nested event filters are not supported). This should be a single andGroup of dimensionOrMetricFilter or notExpression; ANDs of ORs are not supported. Also, if it includes a filter for "eventCount", only that one will be considered; all the other filters will be ignored.

AudienceSequenceFilter

Defines filters that must occur in a specific order for the user to be a member of the Audience.

JSON representation 
{
  "scope": enum (AudienceFilterScope),
  "sequenceMaximumDuration": string,
  "sequenceSteps": [
    {
      object (AudienceSequenceStep)
    }
  ]
}
Fields
scope

enum (AudienceFilterScope)

Required. Immutable. Specifies the scope for this filter.
sequenceMaximumDuration

string (Duration format)

Optional. Defines the time period in which the whole sequence must occur.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
sequenceSteps[]

object (AudienceSequenceStep)

Required. An ordered sequence of steps. A user must complete each step in order to join the sequence filter.

AudienceSequenceStep

A condition that must occur in the specified step order for this user to match the sequence.

JSON representation 
{
  "scope": enum (AudienceFilterScope),
  "immediatelyFollows": boolean,
  "constraintDuration": string,
  "filterExpression": {
    object (AudienceFilterExpression)
  }
}
Fields
scope

enum (AudienceFilterScope)

Required. Immutable. Specifies the scope for this step.
immediatelyFollows

boolean

Optional. If true, the event satisfying this step must be the very next event after the event satisfying the last step. If unset or false, this step indirectly follows the prior step; for example, there may be events between the prior step and this step. It is ignored for the first step.
constraintDuration

string (Duration format)

Optional. When set, this step must be satisfied within the constraintDuration of the previous step (For example, t[i] - t[i-1] <= constraintDuration). If not set, there is no duration requirement (the duration is effectively unlimited). It is ignored for the first step.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
filterExpression

object (AudienceFilterExpression)

Required. Immutable. A logical expression of Audience dimension, metric, or event filters in each step.

AudienceClauseType

Specifies whether this is an include or exclude filter clause.

Enums
AUDIENCE_CLAUSE_TYPE_UNSPECIFIED Unspecified clause type.
INCLUDE Users will be included in the Audience if the filter clause is met.
EXCLUDE Users will be excluded from the Audience if the filter clause is met.

Methods

archive

 Archives an Audience on a property.

create

 Creates an Audience.

get

 Lookup for a single Audience.

list

 Lists Audiences on a property.

patch

 Updates an Audience on a property.