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

必要欄位。要從中擷取資料的 Analytics (分析) 資料檢視 ID。每個 SearchUserActivityRequest 都必須包含 viewId。
user

object(User)

必要欄位。要查詢的不重複使用者 ID。每個 SearchUserActivityRequest 都必須包含此欄位。
activityTypes[]

enum(ActivityType)

要求的所有活動類型集合。回應中只會傳回符合這些類型的景點。如果留空，系統就會傳回所有活動。
pageSize

number

頁面大小用於分頁，並指定傳回的資料列數量上限。頁面大小必須大於 0。如果這個值為 0，或是未指定該欄位，則要求會傳回每頁預設的 1000 列。

pageToken

string

用於取得下一頁結果的接續權杖。將這個參數新增至要求中，會傳回 pageToken 後方的資料列。pageToken 應是針對 SearchUserActivityRequest 要求回應的 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 未指定使用者 ID 類型時，系統會使用的預設類型為 CLIENT_ID。
USER_ID 可能在一或多部裝置和/或瀏覽器上與內容互動的同一名使用者 (例如已登入帳戶的使用者)。
CLIENT_ID 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 傳送的命中記錄為「網站」，從 Mobile SDK 傳送的命中則會記錄為「應用程式」。您可以在 Measurement Protocol 中覆寫這些值。

activities[]

object(Activity)

代表在這個工作階段中每個活動的詳細檢視畫面。
sessionDate

string

這個工作階段的日期，採用 ISO-8601 格式。

活動

「活動」代表使用者活動的資料，請注意，「活動」與命中不同，一次命中可能會導致多個活動。舉例來說，如果命中包含交易和目標達成，這次命中會有兩個活動原型，一個代表「ECOMMERCE」，另一個代表「目標」。反之，多次命中也可以建構一項 Activity。在傳統版電子商務中，單筆交易的資料可能會透過多筆命中傳送。這些命中會併入一個 ECOMMERCE 活動。

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 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，範例："2014-10-02T15:01:23.045123456Z"。
source

string

參照連結網址的來源。如果是手動廣告活動追蹤，這個值是 utm_source 廣告活動追蹤參數的值。AdWords 自動標記是 google。如果您沒有使用這兩者，則指使用者來自來源的網域 (例如 document.referrer)。也可能包含通訊埠位址。如果使用者沒有參照網址，其值會是 (直接)。
medium

string

參照連結網址的類型。如果是手動廣告活動追蹤，這個值是 utm_medium 廣告活動追蹤參數的值。AdWords 自動標記是指單次點擊出價。如果使用者來自 Google Analytics (分析) 偵測到的搜尋引擎，則屬於自然搜尋。如果參照網址不是搜尋引擎，就是參照連結網址。如果使用者直接造訪資源且 document.referrer 為空白，其值會是 (無)。

channelGrouping

string

與這個資料檢視的使用者工作階段相關的管道分組 (由資料檢視的管道分組定義)。

campaign

string

如果是手動廣告活動追蹤，這個值是 utm_campaign 廣告活動追蹤參數的值。AdWords 自動標記是指您使用該資源的線上廣告活動名稱。如果您同時使用兩者，則會看到「(未設定)」。

keyword

string

如果是手動廣告活動追蹤，這個值是 utm_term 廣告活動追蹤參數的值。針對 AdWords 流量，關鍵字包含最相符的指定條件。對於多媒體廣告聯播網，由於多個指定條件可能導致廣告顯示，該廣告會傳回 Google Ads 選擇的最佳指定條件。可以是 display_keyword、網站刊登位置、boomuserlist、user_interest、年齡或性別。否則該值為「(未設定)」。
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

網頁上與使用者互動的物件。例如：「影片」。
eventAction

string

與物件互動的類型。例如「play」。
eventLabel

string

附加在事件中的標籤。

eventValue

string (int64 format)

與事件相關聯的數值。

eventCount

string (int64 format)

這個活動中這類事件的數量。

試試看！