Core Reporting API: сегменты

В этом документе описывается синтаксис сегментов и рекомендации по работе с ними в Core Reporting API.

Введение

Core Reporting API позволяет запрашивать сегменты двумя способами:

  1. С использованием числового идентификатора встроенного или специального сегмента.
  2. Динамическое указание сегмента во время выполнения запроса.

Идентификаторы сегментов

Встроенные и специальные сегменты можно запрашивать в Core Reporting API по идентификатору. Чтобы извлечь все доступные пользователю сегменты, вызовите метод list коллекции Segments в Google Analytics Management API. Идентификатор сегмента размещается в свойстве id ресурса Segment.

Подробнее об идентификаторах сегментов в API…

Динамические сегменты

Сегмент также можно создавать и использовать динамически во время выполнения запроса к API. Как правило, при этом необходимо учитывать следующие варианты выбора:

  1. Пользователи и сеансы
  2. Условия и последовательности
  3. Области действия показателей

Эти вопросы рассматриваются ниже. Подробнее о синтаксисе динамических сегментов…

Какие параметры и показатели можно использовать в сегментах
Подробнее о том, какие параметры и показатели можно использовать в сегментах, читайте здесь.

1. Пользователи и сеансы

Настройте выбор пользователей, сеансов или одновременно обоих параметров.

  • users:: – выбор пользователей.
  • sessions:: – выбор сеансов.
  • Если одновременно заданы условия для параметров users:: и sessions::
    1. Сначала применяются условия для пользователей и возвращаются соответствующие сеансы.
    2. Затем применяются условия для выбранных на первом шаге сеансов.

Пример:

  • Выбор пользователей, которые хотя бы один раз заходили на сайт с помощью браузера Chrome.
    • users::condition::ga:browser==Chrome
  • Выбор сеансов, выполненных с помощью браузера Chrome.
    • sessions::condition::ga:browser==Chrome
  • Выбор сеансов, которые инициированы из Лондона пользователями, хотя бы один раз посещавшими ваш сайт с помощью браузера Chrome.
    • users::condition::ga:browser==Chrome;sessions::condition::ga:city==London

Подробнее читайте в разделе conditionScope.

2. Условия и последовательности

Далее следует задать условия или последовательности.

Условия

Задаются с помощью префикса condition::. Пример:

  • Выбор посетителей из Лондона, использующих браузер Chrome.
    • users::condition::ga:city==London;ga:browser==Chrome

Последовательности

Последовательности условий могут состоять из нескольких шагов, каждый из которых определяется одним или несколькими условиями параметров или показателей.

Чтобы задать последовательность, укажите префикс sequence:: и затем оператор (;–>>) или, непосредственно после, оператор (;–>). Пример:

  • Выбор посетителей, которые впервые использовали компьютер, а затем мобильное устройство. Для сегментации сначала находятся все сеансы пользователя. Затем происходит проверка т, был ли у него сеанс на мобильном устройстве после сеанса на компьютере.
    • users::sequence::ga:deviceCategory==desktop;->>ga:deviceCategory==mobile
  • На каждом этапе можно определять несколько условий.
    • users::sequence::ga:deviceCategory==desktop;ga:operatingSystem==Windows->>ga:deviceCategory==mobile;ga:operatingSystem==Android
  • Условия и последовательности для сегмента можно объединять с помощью логического оператора И (";").
    • users::condition::ga:totalEvents>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile

Подробнее читайте в разделе conditionType. Также ознакомьтесь с другими примерами условий и последовательностей в справке по сегментам.

3. Области действия показателей

Область действия показателя указывает, на каком уровне он определен: обращение, сеанс или пользователь. Например, показатели ga:pageviews и ga:transactions используются в обращениях и определяются на соответствующем уровне. Показатели ga:sessionDuration и ga:bounces имеют одно значение на сеанс и, соответственно, область действия на уровне сеанса. Областью действия верхнего уровня является пользователь, нижнего – обращение.

Область действия значений показателей, используемых в отчетах, может расширяться по сравнению с основной. Например, чтобы использовать показатели ga:pageviews и ga:transactions на уровнях сеанса или пользователя, достаточно добавить их для каждого обращения, связанного с соответствующими сеансами или пользователями.

Также можно указать область действия условия показателя, то есть уровень, на котором оно применяется. Области действия показателей задаются с помощью префиксов perUser::, perSession:: и perHit::.

Пример:

  • Выбор пользователей, потративших на сайте минимум 10 долл. США (общая ценность не менее 10 долл. США).
    users::condition::perUser::ga:transactionRevenue>=10
    
  • Выбор пользователей, потративших минимум 10 долл. США за сеанс.
    users::condition::perSession::ga:transactionRevenue>=10
    

Ограничения области действия

Чтобы гарантировать правильность запроса, Core Reporting API проверяет области действия показателей по следующим правилам:

  1. Заданная область действия показателя не должна быть шире области родительского элемента (указывается с помощью префиксов users:: или sessions::).
  2. Заданная область действия показателя должна быть шире его основной области, определенной в модели данных. Полный список показателей и их основных областей действия представлен здесь.

Вот примеры допустимых областей действия показателей:

  • Области действия показателя и условия совпадают (уровень пользователя).
    • users::condition::perUser::ga:transactionRevenue>10
  • Область действия условия шире, чем у показателя (например, пользователь и сеанс).
    • users::condition::perSession::ga:transactionRevenue>10
  • Показатель ga:totalEvents отражает данные на уровне обращений, поэтому его возможные области действия: perHit::, perSession:: и perUser::, ведь все они больше или идентичны области действия, характерной для уровня обращений.
    • users::condition::perHit::ga:totalEvents>5
    • users::condition::perSession::ga:totalEvents>5

Области действия, которые не пройдут проверку:

  • Этот сегмент не пройдет проверку, поскольку область действия его родительского условия уже, чем у показателя (сеанс и пользователь).
    • sessions::condition::perUser::ga:transactionRevenue>10
  • Для показателя уровня сеанса задана область действия ОБРАЩЕНИЕ.
    • users::condition::perHit::ga:sessionDuration>60

Область действия по умолчанию

Если область действия показателя не задана, она по умолчанию приравнивается к области действия условия. Например, для всех условий показателей в следующем сегменте будет задана область действия ПОЛЬЗОВАТЕЛЬ: users::condition::ga:transactionRevenue>=10;ga:sessionDuration>60

Справка по синтаксису динамических сегментов

Общий синтаксис

Определение сегмента имеет формат segment=<segmentCondition>+, то есть содержит одно или несколько выражений условий segmentCondition.

Условие <segmentCondition> определяется следующим образом: <conditionScope><conditionType><dimensionOrMetricConditions>

Пояснения:
conditionScope – это область действия верхнего уровня для условий.
conditionType – тип условий.
dimensionOrMetricConditions – условия параметров и показателей или дальнейшие шаги последовательности.

conditionScope

Задает область действия верхнего уровня для условий. Допустимые значения:

  • users:: – выбор пользователей.
  • sessions:: – выбор сеансов.

Ограничения и рекомендации по использованию conditionScope:

  • Если в одном сегменте задается несколько условий для пользователей и сеансов, они объединяются с помощью логического оператора И.
  • Условия для выбора одновременно пользователей и сеансов также должны объединяться с помощью оператора И. Если заданы одновременно условия для пользователей и сеансов, сначала находятся все соответствующие пользователи, после чего применяются условия для связанных с ними сеансов.
  • Для условий на уровне пользователей диапазон дат не должен превышать 90 дней.
  • Область действия условия также по умолчанию применяется ко всем нижестоящим условиям показателей. Подробнее об уровнях областей действия…

conditionType

Задает тип условий. Допустимые значения:

  • condition:: – простое условие.
  • sequence:: – последовательность условий.

Ограничения и рекомендации по использованию conditionType:

  • Если в одном сегменте задается несколько простых условий и последовательностей, они всегда объединяются с помощью логического оператора И.
  • Максимальная длина последовательности ограничена 10 шагами.

Простые условия

Состоит из одного или нескольких условий параметров или показателей.

Допустимые операторы для простых условий:

Синтаксис простых условий:

condition::<dimensionOrMetricConditions>

Примеры простых условий:

  • users::condition::ga:transactionRevenue>10;ga:sessionDuration>60
  • Чтобы найти дополнение для простого условия, содержащего несколько условий параметров или показателей, можно использовать высокоуровневый оператор отрицания. Пример: users::condition::!ga:transactionRevenue>10;ga:sessionDuration>60

Исключающие условия

С помощью исключающих условий создаются сегменты, не соответствующие заданным требованиям.

Оператор НЕ (символ "!") позволяет исключить сеансы, соответствующие условию.

Чтобы исключить сеансы, в которых страница выхода точно соответствует пути к главной странице, используйте следующее выражение:
sessions::condition::!ga:exitPagePath==/

Множественные условия

Несколько условий на уровне пользователя можно группировать с помощью одного префикса users:: или отдельного префикса users:: для каждого условия. То же самое относится к условиям уровня сеанса.

Например, следующие два сегмента эквивалентны. В обоих случаях условия condition1 и condition2 объединяются с помощью оператора И для выбора пользователей:
users::<condition1>;<condition2>
users::<condition1>users::<condition2>

Последовательности условий

Последовательности условий могут состоять из нескольких шагов, каждый из которых определяется одним или несколькими условиями параметров или показателей. Шаги объединяются с помощью специальных операторов последовательности.

Допустимые операторы:

  • –>> указывает, что предыдущий шаг предшествует следующему.
  • –> указывает, что предыдущий шаг непосредственно предшествует следующему.

Синтаксис условий последовательности:

sequence:: NOT? FIRST_HIT_MATCHES_FIRST_STEP? (AND (PRECEDES|IMMEDIATELY_PRECEDES) <step>)*

Пояснения:

NOT – представлено с помощью !
FIRST_HIT_MATCHES_FIRST_STEP – представлено с помощью ^
PRECEDES – представлено с помощью ;–>>
IMMEDIATELY_PRECEDES – представлено с помощью ;–>
step – представлено с помощью <dimensionOrMetricConditions>

Примеры последовательностей условий:

  • users::sequence::ga:deviceCategory==desktop;->ga:deviceCategory==tablet
  • Чтобы найти дополнение для последовательности, которая содержит несколько этапов либо условий параметров или показателей, можно использовать высокоуровневый оператор отрицания. Пример: users::sequence::!ga:deviceCategory==desktop;->ga:deviceCategory==tablet
  • Оператор ^ указывает, что первый шаг соответствует первому обращению для первого сеанса за указанный диапазон дат. Пример: users::sequence::^ga:deviceCategory==desktop;->ga:deviceCategory==tablet

Условия с датой сеанса

Сегменты поддерживают синтаксис dateOfSession. С помощью оператора "Между" (<>) можно ограничить сегмент группой пользователей, инициировавших сеанс за указанный период времени. Максимальный диапазон дат для параметра dateOfSession составляет 31 день. Подробный пример.

Условия параметров и показателей

Объединение условий

Условия параметров можно объединять с помощью логических операторов И (";") и ИЛИ (","), последний из которых имеет более высокий приоритет.

При этом используется такой же синтаксис, что и при объединении фильтров. Подробнее…

Операторы

В следующей таблице описываются все операторы сегментов и указывается, можно ли их использовать с параметрами и показателями.

Оператор Описание Поддерживается в условиях параметров? Поддерживается в условиях показателей?
== Равно или точно соответствует. Да
Пример: ga:city==London
Да
Пример: ga:adCost==10
!= Не равно или не соответствует точно. Да
Пример: ga:city!=Лондон
Да
Пример: ga:adCost!=10
< Меньше. Да, только для числовых значений.
Пример: ga:hour<12
Да
Пример: ga:adCost<10
<= Меньше или равно. Да, только для числовых значений.
Пример: ga:hour<=12
Да
Пример: ga:adCost<=10
> Больше. Да, только для числовых значений.
Пример: ga:hour>12
Да
Пример: ga:adCost>10
>= Больше или равно. Да, только для числовых значений.
Пример: ga:hour>=12
Да
Пример: ga:adCost>=10
<> Между (значение принадлежит заданному диапазону1). Да, только для числовых значений.
Пример: ga:hour<>1_12
Да
Пример: ga:adCost<>10_20
[] В списке (значение входит в список2). Да
Пример: ga:browser[]Chrome|Firefox|Opera
Нет
=@ Содержит подстроку. Да
Пример: ga:keyword=@shoes
Нет
!@ Не содержит подстроку. Да
Пример: ga:keyword!@обувь
Нет
=~ Содержит совпадение для регулярного выражения. Да
Пример: ga:keyword=~shoes
Нет
!~ Не содержит совпадение для регулярного выражения. Да
Пример: ga:keyword!~обувь
Нет

1Оператор "между" <>
Позволяет запросить значения в заданном диапазоне (включительно) и может использоваться с показателями и параметрами, имеющими числовые значения, например ga:hour. Минимальное и максимальное значения диапазона разделяются символом подчеркивания.

Синтаксис:
{названиеПараметраИлиПоказателя}<>{минЗначение}_{максЗначение}

Пример:
Выбрать сеансы, зарегистрированные в период с 12 до 23 часов.
sessions::condition::ga:hour<>12_23

2Оператор "в списке" []
Позволяет запросить значения из заданного списка и может использоваться только с параметрами. Значения в списке разделяются символом вертикальной черты "|". Если значение содержит символ "|", его необходимо экранировать.

Синтаксис:
{названиеПараметра}[]{значение1}|{значение2}|...

Ограничения:
Не более 10 значений на одно условие параметра, то есть ga:city[]city1|city2|...|city10.

Пример:
Выбрать сеансы, исходящие из браузеров Chrome, Firefox и Opera.
sessions::condition::ga:browser[]Chrome|Firefox|Opera

Экранирование специальных символов

Специальные символы "," и ";" в выражениях необходимо экранировать. Пример: ga:keyword==nike\,shoes

Подробнее об условиях параметров и показателей…

Ограничения

В отношении условий параметров и показателей действуют следующие ограничения:

  • Не более 10 условий параметров или показателей на сегмент.
  • Максимальная длина выражения, определяющего условие параметра, не более 1024 символов.

Перенос динамических сегментов прежних версий

Устаревшие динамические сегменты с префиксом dynamic:: в текущей версии синтаксиса эквивалентны сегментам уровня сеанса с условиями параметров и показателей. Чтобы работать с ними, необходимо заменить префикс dynamic:: префиксом sessions::condition::. Например, следующий сегмент:

dynamic::ga:browser==Chrome
эквивалентен этому:
sessions::condition::ga:browser==Chrome

Примеры сегментов

1. Демография. Мужчины с американского континента, увлекающиеся видеоиграми и говорящие на американском английском.

В первую очередь применяются сегменты на основе пользователей. Соответствующее условие возвращает пользователей мужского пола, которые интересуются играми. После этого применяются условия, позволяющие выбрать сеансы, которые были инициированы пользователями с американского континента с выбранным языком EN-US.

users::condition::ga:userGender==Male;users::condition::ga:interestAffinityCategory==Games ; sessions::condition::ga:region==Americas;sessions::condition::ga:language==en-u

2. Действия пользователей. Пользователи, которые выполнили более 100 сеансов, не посещали сайт в последние 7 дней, выполняют более 2 транзакций в течение сеанса и проводят на сайте более 100 секунд за сеанс.

users::condition::ga:sessions>100;ga:daysSinceLastSession>=7; perSession::ga:transactions>2;perSession::ga:sessionDuration>100

3. Сеансы. Выбор сеансов, выполненных из браузера Chrome пользователями на территории США (US), с количеством исключений на обращение более 1 И выбор пользователей с общей ценностью более 10 долл. США и количеством выходов на сеанс не более 2.

sessions::condition::ga:browser==Chrome;ga:country==US;perHit::ga:exceptions>1; users::condition::perSession::ga:exits<2

4. Сеанс с последовательностью. Выбор сеансов со следующими критериями: – Первый шаг: браузер Chrome и количество событий за обращение: более 5. И – Первый шаг: компьютер. – Второй шаг: мобильное устройство.

sessions::sequence::ga:browser==Chrome;condition::perHit::ga:totalEvents>5;users::sequence::ga:deviceCategory==desktop->>ga:deviceCategory=mobile

5. Дата сеанса. Выбор пользователей, первый сеанс которых состоялся в диапазоне между 20 и 30 мая 2014 г. и длился более 600 сек.

users::sequence::^ga:sessionCount==1;dateOfSession<>2014-05-20_2014-05-30;->>ga:sessionDurationBucket>600

Справка по основной области применения показателей

Показатель Основная область применения
ga:adClicksОБРАЩЕНИЕ
ga:adCostОБРАЩЕНИЕ
ga:adsenseAdsClicksОБРАЩЕНИЕ
ga:adsenseAdsViewedОБРАЩЕНИЕ
ga:adsenseAdUnitsViewedОБРАЩЕНИЕ
ga:adsenseCTRОБРАЩЕНИЕ
ga:adsenseECPMОБРАЩЕНИЕ
ga:adsensePageImpressionsОБРАЩЕНИЕ
ga:adsenseRevenueОБРАЩЕНИЕ
ga:avgDomainLookupTimeОБРАЩЕНИЕ
ga:avgDomContentLoadedTimeОБРАЩЕНИЕ
ga:avgDomInteractiveTimeОБРАЩЕНИЕ
ga:avgEventValueОБРАЩЕНИЕ
ga:avgPageDownloadTimeОБРАЩЕНИЕ
ga:avgPageLoadTimeОБРАЩЕНИЕ
ga:avgRedirectionTimeОБРАЩЕНИЕ
ga:avgScreenviewDurationОБРАЩЕНИЕ
ga:avgSearchDepthОБРАЩЕНИЕ
ga:avgSearchDurationОБРАЩЕНИЕ
ga:avgSearchResultViewsОБРАЩЕНИЕ
ga:avgServerConnectionTimeОБРАЩЕНИЕ
ga:avgServerResponseTimeОБРАЩЕНИЕ
ga:avgUserTimingValueОБРАЩЕНИЕ
ga:costPerConversionОБРАЩЕНИЕ
ga:costPerGoalConversionОБРАЩЕНИЕ
ga:costPerTransactionОБРАЩЕНИЕ
ga:CPCОБРАЩЕНИЕ
ga:CPMОБРАЩЕНИЕ
ga:CTRОБРАЩЕНИЕ
ga:domainLookupTimeОБРАЩЕНИЕ
ga:domContentLoadedTimeОБРАЩЕНИЕ
ga:domInteractiveTimeОБРАЩЕНИЕ
ga:domLatencyMetricsSampleОБРАЩЕНИЕ
ga:eventValueОБРАЩЕНИЕ
ga:exceptionsОБРАЩЕНИЕ
ga:exceptionsPerScreenviewОБРАЩЕНИЕ
ga:fatalExceptionsОБРАЩЕНИЕ
ga:fatalExceptionsPerScreenviewОБРАЩЕНИЕ
ga:goalAbandonRateAllОБРАЩЕНИЕ
ga:goalAbandonsAllОБРАЩЕНИЕ
ga:goalCompletionsAllОБРАЩЕНИЕ
ga:goalStartsAllОБРАЩЕНИЕ
ga:goalValueAllОБРАЩЕНИЕ
ga:goalValueAllPerSearchОБРАЩЕНИЕ
ga:goalXXAbandonRateОБРАЩЕНИЕ
ga:goalXXAbandonsОБРАЩЕНИЕ
ga:goalXXCompletionsОБРАЩЕНИЕ
ga:goalXXStartsОБРАЩЕНИЕ
ga:goalXXValueОБРАЩЕНИЕ
ga:impressionsОБРАЩЕНИЕ
ga:itemQuantityОБРАЩЕНИЕ
ga:itemRevenueОБРАЩЕНИЕ
ga:itemsPerPurchaseОБРАЩЕНИЕ
ga:localItemRevenueОБРАЩЕНИЕ
ga:localTransactionRevenueОБРАЩЕНИЕ
ga:localTransactionShippingОБРАЩЕНИЕ
ga:localTransactionTaxОБРАЩЕНИЕ
ga:marginОБРАЩЕНИЕ
ga:metricXXОБРАЩЕНИЕ
ga:pageDownloadTimeОБРАЩЕНИЕ
ga:pageLoadSampleОБРАЩЕНИЕ
ga:pageLoadTimeОБРАЩЕНИЕ
ga:pageValueОБРАЩЕНИЕ
ga:pageviewsОБРАЩЕНИЕ
ga:percentSearchRefinementsОБРАЩЕНИЕ
ga:redirectionTimeОБРАЩЕНИЕ
ga:revenuePerItemОБРАЩЕНИЕ
ga:revenuePerTransactionОБРАЩЕНИЕ
ga:ROIОБРАЩЕНИЕ
ga:RPCОБРАЩЕНИЕ
ga:screenviewsОБРАЩЕНИЕ
ga:searchDepthОБРАЩЕНИЕ
ga:searchDurationОБРАЩЕНИЕ
ga:searchGoalConversionRateAllОБРАЩЕНИЕ
ga:searchGoalXXConversionRateОБРАЩЕНИЕ
ga:searchRefinementsОБРАЩЕНИЕ
ga:searchResultViewsОБРАЩЕНИЕ
ga:searchUniquesОБРАЩЕНИЕ
ga:serverConnectionTimeОБРАЩЕНИЕ
ga:serverResponseTimeОБРАЩЕНИЕ
ga:socialActivitiesОБРАЩЕНИЕ
ga:socialInteractionsОБРАЩЕНИЕ
ga:socialInteractionsPerSessionОБРАЩЕНИЕ
ga:speedMetricsSampleОБРАЩЕНИЕ
ga:timeOnScreenОБРАЩЕНИЕ
ga:totalEventsОБРАЩЕНИЕ
ga:totalValueОБРАЩЕНИЕ
ga:transactionRevenueОБРАЩЕНИЕ
ga:transactionsОБРАЩЕНИЕ
ga:transactionShippingОБРАЩЕНИЕ
ga:transactionTaxОБРАЩЕНИЕ
ga:uniqueAppviewsОБРАЩЕНИЕ
ga:uniqueEventsОБРАЩЕНИЕ
ga:uniquePageviewsОБРАЩЕНИЕ
ga:uniquePurchasesОБРАЩЕНИЕ
ga:uniqueScreenviewsОБРАЩЕНИЕ
ga:uniqueSocialInteractionsОБРАЩЕНИЕ
ga:userTimingSampleОБРАЩЕНИЕ
ga:userTimingValueОБРАЩЕНИЕ
ga:adsenseExitsСЕАНС
ga:avgTimeOnPageСЕАНС
ga:avgSessionDurationСЕАНС
ga:bouncesСЕАНС
ga:entranceBounceRateСЕАНС
ga:entranceRateСЕАНС
ga:entrancesСЕАНС
ga:eventsPerSessionWithEventСЕАНС
ga:exitRateСЕАНС
ga:exitsСЕАНС
ga:goalConversionRateAllСЕАНС
ga:goalValuePerSessionСЕАНС
ga:goalXXConversionRateСЕАНС
ga:organicSearchesСЕАНС
ga:pageviewsPerSessionСЕАНС
ga:percentSessionsWithSearchСЕАНС
ga:screenviewsPerSessionСЕАНС
ga:searchExitRateСЕАНС
ga:searchExitsСЕАНС
ga:searchSessionsСЕАНС
ga:sessionDurationСЕАНС
ga:transactionRevenuePerSessionСЕАНС
ga:transactionsPerSessionСЕАНС
ga:bounceRateСЕАНС
ga:sessionsСЕАНС
ga:sessionsWithEventСЕАНС
ga:newSessionsПОЛЬЗОВАТЕЛЬ
ga:percentNewSessionsПОЛЬЗОВАТЕЛЬ
ga:usersПОЛЬЗОВАТЕЛЬ