- HTTP 要求
- 要求主體
- 回應主體
- 授權範圍
- 使用者
- UserIdType
- ActivityType
- UserActivitySession
- 活動
- CustomDimension
- PageviewData
- ScreenviewData
- EcommerceData
- ECommerceAction
- TransactionData
- ProductData
- EcommerceType
- GoalSetData
- GoalData
- EventData
- 試試看!
傳回使用者活動資料。
HTTP 要求
POST https://analyticsreporting.googleapis.com/v4/userActivity:search
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 | |
---|---|
{ "dateRange": { object( |
欄位 | |
---|---|
dateRange |
要擷取使用者活動的日期範圍。如未提供日期範圍,預設日期範圍會是 (startDate:目前日期 - 7 天,endDate:目前日期 - 1 天)。 |
viewId |
必要欄位。要從中擷取資料的 Analytics (分析) 資料檢視 ID。每個 SearchUserActivityRequest 都必須包含 |
user |
必要欄位。要查詢的不重複使用者 ID。每個 SearchUserActivityRequest 都必須包含此欄位。 |
activityTypes[] |
要求的所有活動類型集合。回應中只會傳回符合這些類型的景點。如果留空,系統就會傳回所有活動。 |
pageSize |
頁面大小用於分頁,並指定傳回的資料列數量上限。頁面大小必須大於 0。如果這個值為 0,或是未指定該欄位,則要求會傳回每頁預設的 1000 列。 |
pageToken |
用於取得下一頁結果的接續權杖。將這個參數新增至要求中,會傳回 pageToken 後方的資料列。pageToken 應是針對 SearchUserActivityRequest 要求回應的 nextPageToken 參數傳回的值。 |
回應主體
如果成功,回應主體即會包含具有以下結構的資料:
userActivity:get
呼叫的回應。
JSON 表示法 | |
---|---|
{
"sessions": [
{
object( |
欄位 | |
---|---|
sessions[] |
每筆記錄都代表一個工作階段 (裝置詳細資料、持續時間等)。 |
totalRows |
這項查詢 (橫跨不同網頁) 傳回的資料列總數。 |
nextPageToken |
請將這個權杖傳遞至 SearchUserActivityRequest 以擷取下一頁。 |
sampleRate |
|
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/analytics.readonly
https://www.googleapis.com/auth/analytics
使用者
包含可用於識別特定使用者的資訊。
JSON 表示法 | |
---|---|
{
"type": enum( |
欄位 | |
---|---|
type |
要求中的使用者類型。 |
userId |
要求取得資料的使用者專屬 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( |
欄位 | |
---|---|
sessionId |
工作階段的專屬 ID。 |
deviceCategory |
使用的裝置類型:「手機」、「平板電腦」等。 |
platform |
發生活動的平台:「Android」、「ios」等。 |
dataSource |
這是匹配的資料來源。根據預設,系統會將 analytics.js 傳送的命中記錄為「網站」,從 Mobile SDK 傳送的命中則會記錄為「應用程式」。您可以在 Measurement Protocol 中覆寫這些值。 |
activities[] |
代表在這個工作階段中每個活動的詳細檢視畫面。 |
sessionDate |
這個工作階段的日期,採用 ISO-8601 格式。 |
活動
「活動」代表使用者活動的資料,請注意,「活動」與命中不同,一次命中可能會導致多個活動。舉例來說,如果命中包含交易和目標達成,這次命中會有兩個活動原型,一個代表「ECOMMERCE」,另一個代表「目標」。反之,多次命中也可以建構一項 Activity。在傳統版電子商務中,單筆交易的資料可能會透過多筆命中傳送。這些命中會併入一個 ECOMMERCE 活動。
JSON 表示法 | |
---|---|
{ "activityTime": string, "source": string, "medium": string, "channelGrouping": string, "campaign": string, "keyword": string, "hostname": string, "landingPagePath": string, "activityType": enum( |
欄位 | ||
---|---|---|
activityTime |
活動的時間戳記。 RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,範例: |
|
source |
參照連結網址的來源。如果是手動廣告活動追蹤,這個值是 utm_source 廣告活動追蹤參數的值。AdWords 自動標記是 google。如果您沒有使用這兩者,則指使用者來自來源的網域 (例如 document.referrer)。也可能包含通訊埠位址。如果使用者沒有參照網址,其值會是 (直接)。 |
|
medium |
參照連結網址的類型。如果是手動廣告活動追蹤,這個值是 utm_medium 廣告活動追蹤參數的值。AdWords 自動標記是指單次點擊出價。如果使用者來自 Google Analytics (分析) 偵測到的搜尋引擎,則屬於自然搜尋。如果參照網址不是搜尋引擎,就是參照連結網址。如果使用者直接造訪資源且 document.referrer 為空白,其值會是 (無)。 |
|
channelGrouping |
與這個資料檢視的使用者工作階段相關的管道分組 (由資料檢視的管道分組定義)。 |
|
campaign |
如果是手動廣告活動追蹤,這個值是 utm_campaign 廣告活動追蹤參數的值。AdWords 自動標記是指您使用該資源的線上廣告活動名稱。如果您同時使用兩者,則會看到「(未設定)」。 |
|
keyword |
如果是手動廣告活動追蹤,這個值是 utm_term 廣告活動追蹤參數的值。針對 AdWords 流量,關鍵字包含最相符的指定條件。對於多媒體廣告聯播網,由於多個指定條件可能導致廣告顯示,該廣告會傳回 Google Ads 選擇的最佳指定條件。可以是 display_keyword、網站刊登位置、boomuserlist、user_interest、年齡或性別。否則該值為「(未設定)」。 |
|
hostname |
發出追蹤要求的主機名稱。 |
|
landingPagePath |
使用者工作階段中的第一個網頁或到達網頁。 |
|
activityType |
此活動的類型。 |
|
customDimension[] |
列出與此活動相關聯的所有自訂維度。 |
|
聯集欄位 activity_details 。視 activity_type 而定,系統只會設定下列其中一個欄位。activity_details 只能採用下列其中一種設定: |
||
pageview |
如果 |
|
appview |
如果 |
|
ecommerce |
如果 |
|
goals |
這個欄位包含 |
|
event |
這個欄位包含事件的所有詳情,如果 |
CustomDimension
自訂維度。
JSON 表示法 | |
---|---|
{ "index": number, "value": string } |
欄位 | |
---|---|
index |
自訂維度的運算單元數量。 |
value |
自訂維度的值。預設值 (即空白字串) 代表清除細目/訪客範圍自訂維度值。 |
PageviewData
代表訪客瀏覽網頁時所收集的詳細資料。
JSON 表示法 | |
---|---|
{ "pagePath": string, "pageTitle": string } |
欄位 | |
---|---|
pagePath |
訪客瀏覽的網頁網址。 |
pageTitle |
訪客瀏覽的網頁標題。 |
ScreenviewData
JSON 表示法 | |
---|---|
{ "screenName": string, "mobileDeviceBranding": string, "mobileDeviceModel": string, "appName": string } |
欄位 | |
---|---|
screenName |
畫面名稱。 |
mobileDeviceBranding |
行動裝置製造商或品牌名稱。例如:「Google」、「Apple」等。 |
mobileDeviceModel |
行動裝置型號。例如:「Pixel」、「iPhone」等。 |
appName |
應用程式名稱。 |
EcommerceData
與使用者活動相關的電子商務詳細資料。
JSON 表示法 | |
---|---|
{ "actionType": enum( |
欄位 | |
---|---|
actionType |
與這個電子商務動作相關聯的動作。 |
transaction |
這個電子商務動作的交易明細。 |
products[] |
這筆交易中產品的詳細資料。 |
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 |
購物車中的交易交易 ID (由電子商務追蹤方法提供)。 |
transactionRevenue |
交易的銷售總收益 (不含運費和稅金)。 |
transactionTax |
交易的稅金總額。 |
transactionShipping |
運費總額。 |
ProductData
電子商務交易中的產品詳細資料。
JSON 表示法 | |
---|---|
{ "productSku": string, "productName": string, "itemRevenue": number, "productQuantity": string } |
欄位 | |
---|---|
productSku |
代表產品的專屬代碼。 |
productName |
所購商品的產品名稱,由電子商務追蹤應用程式提供。 |
itemRevenue |
售出產品帶來的總收益。 |
productQuantity |
交易中此產品單位的總數。 |
EcommerceType
這代表要傳回的電子商務資料類型。
列舉 | |
---|---|
ECOMMERCE_TYPE_UNSPECIFIED |
在未指定電子商務活動類型時使用。 |
CLASSIC |
在活動含有傳統版 (非加強型) 電子商務資訊時使用。 |
ENHANCED |
在活動包含加強型電子商務資訊時使用。 |
GoalSetData
代表在某個活動中達成的一組目標。
JSON 表示法 | |
---|---|
{
"goals": [
{
object( |
欄位 | |
---|---|
goals[] |
目前活動中達成的所有目標。 |
GoalData
代表與目標相關的所有詳情。
JSON 表示法 | |
---|---|
{ "goalIndex": number, "goalCompletions": string, "goalValue": number, "goalCompletionLocation": string, "goalPreviousStep1": string, "goalPreviousStep2": string, "goalPreviousStep3": string, "goalName": string } |
欄位 | |
---|---|
goalIndex |
這個欄位可識別為設定檔設定的目標。 |
goalCompletions |
這項活動的目標達成總數。 |
goalValue |
這個目標的價值。 |
goalCompletionLocation |
完成這個目標的網頁網址。 |
goalPreviousStep1 |
達成目標前一步驟的網頁網址 |
goalPreviousStep2 |
目標達成前兩個步驟的網頁網址 |
goalPreviousStep3 |
目標達成前三個步驟的網頁網址。 |
goalName |
目標名稱。 |
EventData
代表與事件相關的所有詳細資料。
JSON 表示法 | |
---|---|
{ "eventCategory": string, "eventAction": string, "eventLabel": string, "eventValue": string, "eventCount": string } |
欄位 | |
---|---|
eventCategory |
網頁上與使用者互動的物件。例如:「影片」。 |
eventAction |
與物件互動的類型。例如「play」。 |
eventLabel |
附加在事件中的標籤。 |
eventValue |
與事件相關聯的數值。 |
eventCount |
這個活動中這類事件的數量。 |