Method: userActivity.search

返回用户活动数据。

HTTP 请求

POST https://analyticsreporting.googleapis.com/v4/userActivity:search

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "dateRange": {
    object(DateRange)
  },
  "viewId": string,
  "user": {
    object(User)
  },
  "activityTypes": [
    enum(ActivityType)
  ],
  "pageSize": number,
  "pageToken": string
}
字段
dateRange

object(DateRange)

用于检索用户活动的日期范围。如果未提供日期范围，则默认日期范围为 (startDate: 当前日期 - 7 天, endDate: 当前日期 - 1 天)。

viewId

string

必需。从中提取数据的 Google Analytics（分析）数据视图 ID。每个 SearchUserActivityRequest 都必须包含 viewId。
user

object(User)

必需。要查询的唯一身份用户 ID。每个 SearchUserActivityRequest 都必须包含此字段。
activityTypes[]

enum(ActivityType)

所请求的所有活动类型的集合。响应中只会返回与这些类型匹配的活动。如果为空，则返回所有 activity。

pageSize

number

页面大小用于分页，并指定返回行的最大数目。页面大小应 > 0。如果值为 0 或未指定此字段，则请求默认每页返回 1000 行。

pageToken

string

获得下一页结果的延续令牌。将此令牌添至请求将返回 pageToken 后的行。在对 SearchUserActivityRequest 请求的响应中，pageToken 应为 nextPageToken 参数中返回的值。

响应正文

如果成功，响应正文将包含结构如下的数据：

userActivity:get 调用的响应。

JSON 表示法 
{
  "sessions": [
    {
      object(UserActivitySession)
    }
  ],
  "totalRows": number,
  "nextPageToken": string,
  "sampleRate": number
}
字段
sessions[]

object(UserActivitySession)

每条记录代表一个会话（设备详细信息、时长等）。
totalRows

number

此查询返回的总行数（跨不同页面）。

nextPageToken

string

应将此令牌传递给 SearchUserActivityRequest 以检索下一页。
sampleRate

number

此字段表示指定请求的采样率，是 0.0 到 1.0 之间的数字。如需了解详情，请参阅开发者指南。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

用户

包含用于唯一地标识特定用户的信息。

JSON 表示法 
{
  "type": enum(UserIdType),
  "userId": string
}
字段
type

enum(UserIdType)

请求中的用户类型。字段 userId 与此类型相关联。

userId

string

要为其请求数据的用户的唯一 ID。

UserIdType

表示各种可用的用户标识类型。

枚举
USER_ID_TYPE_UNSPECIFIED 如果未指定 User Id 类型，则默认使用 CLIENT_ID 类型。
USER_ID 一个用户（例如一个已登录用户账号），该用户可能在一个或多个设备和/或浏览器实例中与内容互动。
CLIENT_ID Google Analytics（分析）分配的 clientId。

ActivityType

枚举
ACTIVITY_TYPE_UNSPECIFIED ActivityType 在响应中绝不会有此值。在请求中使用该类型将导致错误。
PAGEVIEW 因访问者浏览网页而产生活动时使用。
SCREENVIEW 当访问者在移动设备上使用应用时产生了活动，使用此属性。
GOAL 用于表示目标类型是活动。
ECOMMERCE 访问者在网页上进行了一次电子商务交易。
EVENT 在活动为事件时使用。

UserActivitySession

这表示在一段时间内的特定时间内在特定设备上执行的用户会话。

JSON 表示法 
{
  "sessionId": string,
  "deviceCategory": string,
  "platform": string,
  "dataSource": string,
  "activities": [
    {
      object(Activity)
    }
  ],
  "sessionDate": string
}
字段
sessionId

string

会话的唯一 ID。

deviceCategory

string

使用的设备类型：“移动设备”“平板电脑”等。

platform

string

发生活动的平台：“android”、“ios”等。

dataSource

string

某一次命中的数据源。默认情况下，从 analytics.js 发送的命中报告为“网站”，从移动 SDK 发送的命中报告为“应用”。这些值可在 Measurement Protocol 中被替换。

activities[]

object(Activity)

表示此会话中每项活动的详细视图。

sessionDate

string

此会话的日期，采用 ISO-8601 格式。

Activity

Activity 表示用户 Activity 的数据。请注意，活动与命中不同。一次命中可能会导致多个 Activity。例如，如果命中包含一笔交易和一次目标达成，该命中将有两个 Activity proto，一个针对电子商务，另一个针对 GOAL。相反，多次命中也可以构建一个 Activity。在传统电子商务中，一笔交易的数据可能会通过多次命中进行发送。这些命中将合并到一个电子商务活动中。

JSON 表示法 
{
  "activityTime": string,
  "source": string,
  "medium": string,
  "channelGrouping": string,
  "campaign": string,
  "keyword": string,
  "hostname": string,
  "landingPagePath": string,
  "activityType": enum(ActivityType),
  "customDimension": [
    {
      object(CustomDimension)
    }
  ],

  // Union field activity_details can be only one of the following:
  "pageview": {
    object(PageviewData)
  },
  "appview": {
    object(ScreenviewData)
  },
  "ecommerce": {
    object(EcommerceData)
  },
  "goals": {
    object(GoalSetData)
  },
  "event": {
    object(EventData)
  }
  // End of list of possible types for union field activity_details.
}
字段
activityTime

string (Timestamp format)

活动的时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒。示例："2014-10-02T15:01:23.045123456Z"。
source

string

引荐来源。对于人工广告系列跟踪，此值为 utm_source 广告系列跟踪参数的值。对于 AdWords 自动标记，它是 google。如果两者都使用，则使用引荐用户的来源域名（例如 document.referrer）。它还可能包含端口地址。如果用户未通过引荐来源网址进行访问，则其值为 (direct)。

medium

string

引荐类型。对于人工广告系列跟踪，此值为 utm_medium 广告系列跟踪参数的值。对于 AdWords 自动标记，此值为 cpc。如果用户来自被 Google Analytics（分析）检测到的搜索引擎，则属于自然搜索。如果引荐来源网址不是搜索引擎，则它是引荐来源。如果用户直接访问媒体资源，而 document.referrer 为空，则其值为 (none)。

channelGrouping

string

与此数据视图的最终用户会话相关联的渠道组（由该数据视图的渠道分组定义）。

campaign

string

对于人工广告系列跟踪，此值为 utm_campaign 广告系列跟踪参数的值。对于 AdWords 自动标记，此值是指您为媒体资源使用的在线广告系列的名称。如果两者都使用，则其值为“(not set)”。

keyword

string

对于人工广告系列跟踪，此值为 utm_term 广告系列跟踪参数的值。对于 AdWords 流量，其中包含最匹配的定位条件。对于展示广告网络（有多个定位条件可能导致广告展示），则会返回 Google Ads 选择最匹配的定位条件。值可以是 display_keyword、site placement、boomuserlist、user_interest、age 或 gender。否则，其值为 (not set)。

hostname

string

发出跟踪请求的主机名。

landingPagePath

string

用户会话中的第一个网页或着陆页。

activityType

enum(ActivityType)

此活动的类型。

customDimension[]

object(CustomDimension)

与此活动相关联的所有自定义维度的列表。
联合字段 activity_details。根据 activity_type，将仅设置以下字段中的一个。activity_details 只能是下列其中一项：
pageview

object(PageviewData)

如果 activityType 等于 PAGEVIEW，则系统将会设置此值。此字段包含有关访问者和所访问网页的所有详细信息。

appview

object(ScreenviewData)

如果 activityType 等于 SCREEN_VIEW，则系统将会设置此值。

ecommerce

object(EcommerceData)

如果 activityType 等于 ECOMMERCE，则系统将会设置此值。

goals

object(GoalSetData)

此字段包含当 activityType 为 GOAL 时此活动中达成的所有目标的列表。
event

object(EventData)

此字段包含与事件相关的所有详细信息，如果 activityType 等于 EVENT，系统就会设置此字段。

CustomDimension

自定义维度。

JSON 表示法 
{
  "index": number,
  "value": string
}
字段
index

number

自定义维度的槽数。

value

string

自定义维度的值。默认值（即空字符串）表示清除会话/访问者范围自定义维度值。

PageviewData

表示访问者浏览网页时收集的详细信息。

JSON 表示法 
{
  "pagePath": string,
  "pageTitle": string
}
字段
pagePath

string

访问者浏览过的网页的网址。

pageTitle

string

访问者浏览的网页的标题。

ScreenviewData

JSON 表示法 
{
  "screenName": string,
  "mobileDeviceBranding": string,
  "mobileDeviceModel": string,
  "appName": string
}
字段
screenName

string

屏幕的名称。

mobileDeviceBranding

string

移动设备制造商或品牌名称。例如：“Google”“Apple”等。

mobileDeviceModel

string

移动设备型号。例如：“Pixel”“iPhone”等。

appName

string

应用名称。

EcommerceData

与用户活动相关联的电子商务详细信息。

JSON 表示法 
{
  "actionType": enum(ECommerceAction),
  "transaction": {
    object(TransactionData)
  },
  "products": [
    {
      object(ProductData)
    }
  ],
  "ecommerceType": enum(EcommerceType)
}
字段
actionType

enum(ECommerceAction)

与此电子商务操作相关联的操作。

transaction

object(TransactionData)

此电子商务操作的交易详情。

products[]

object(ProductData)

此交易中产品的详细信息。

ecommerceType

enum(EcommerceType)

此电子商务活动的类型。

ECommerceAction

与电子商务操作相关联的所有操作的集合。

枚举
UNKNOWN 操作类型未知。
CLICK 点击浏览商品列表。
DETAILS_VIEW 产品详情浏览。
ADD_TO_CART 将商品添加到购物车。
REMOVE_FROM_CART 从购物车中移除产品。
CHECKOUT 结账。
PAYMENT 完成购买。
REFUND 购买交易退款。
CHECKOUT_OPTION 结账选项。

TransactionData

表示访问者在网页上进行交易时收集的详细信息。

JSON 表示法 
{
  "transactionId": string,
  "transactionRevenue": number,
  "transactionTax": number,
  "transactionShipping": number
}
字段
transactionId

string

电子商务跟踪方法为购物车中的购买提供的交易 ID。

transactionRevenue

number

这笔交易的总销售收入（不含运费和税费）。

transactionTax

number

交易的总税费。

transactionShipping

number

运费总额。

ProductData

电子商务交易中产品的详细信息。

JSON 表示法 
{
  "productSku": string,
  "productName": string,
  "itemRevenue": number,
  "productQuantity": string
}
字段
productSku

string

代表商品的唯一代码。

productName

string

电子商务跟踪应用为已购商品提供的商品名称。

itemRevenue

number

已购买产品项的总收入。

productQuantity

string (int64 format)

交易中此产品的总数。

EcommerceType

这表示要返回的电子商务数据的类型。

枚举
ECOMMERCE_TYPE_UNSPECIFIED 未指定电子商务活动类型时使用。
CLASSIC 当活动包含传统（非增强型）电子商务信息时使用。
ENHANCED 当活动包含增强型电子商务信息时使用。

GoalSetData

表示在活动中达成的一组目标。

JSON 表示法 
{
  "goals": [
    {
      object(GoalData)
    }
  ]
}
字段
goals[]

object(GoalData)

当前活动中已达成的所有目标。

GoalData

表示与目标相关的所有详情。

JSON 表示法 
{
  "goalIndex": number,
  "goalCompletions": string,
  "goalValue": number,
  "goalCompletionLocation": string,
  "goalPreviousStep1": string,
  "goalPreviousStep2": string,
  "goalPreviousStep3": string,
  "goalName": string
}
字段
goalIndex

number

用于标识为配置文件配置的目标。

goalCompletions

string (int64 format)

此活动中的目标达成总次数。

goalValue

number

此目标中的价值。

goalCompletionLocation

string

完成此目标的网页的网址。

goalPreviousStep1

string

目标达成前一步的网页的网址。

goalPreviousStep2

string

目标达成前两个步骤对应的网页的网址。

goalPreviousStep3

string

目标达成前的三个步骤所对应的网页的网址。

goalName

string

目标的名称。

EventData

表示与事件相关的所有详情。

JSON 表示法 
{
  "eventCategory": string,
  "eventAction": string,
  "eventLabel": string,
  "eventValue": string,
  "eventCount": string
}
字段
eventCategory

string

用户与之互动过的页面上的对象。例如：“Video”。

eventAction

string

与对象的互动类型。例如：“播放”。

eventLabel

string

随事件附加的标签。

eventValue

string (int64 format)

与事件相关的数值。

eventCount

string (int64 format)

此 activity 中此类事件的数量。

试试看！