Writes a single user event.

Scopes

You will need authorization for the https://www.googleapis.com/auth/cloud-platform scope to make a valid call.

If unset, the scope for this method defaults to https://www.googleapis.com/auth/cloud-platform. You can set the scope for this method like this: recommendationengine1-beta1 --scope <scope> projects locations-catalogs-event-stores-user-events-write ...

Required Scalar Argument

  • <parent> (string)
    • Required. The parent eventStore resource name, such as "projects/1234/locations/global/catalogs/default_catalog/eventStores/default_event_store".

Required Request Value

The request value is a data-structure with various fields. Each field may be a simple scalar or another data-structure. In the latter case it is advised to set the field-cursor to the data-structure's field to specify values more concisely.

For example, a structure like this:

GoogleCloudRecommendationengineV1beta1UserEvent:
  event-detail:
    experiment-ids: [string]
    page-view-id: string
    recommendation-token: string
    referrer-uri: string
    uri: string
  event-source: string
  event-time: string
  event-type: string
  product-event-detail:
    cart-id: string
    list-id: string
    purchase-transaction:
      costs: { string: number }
      currency-code: string
      id: string
      revenue: number
      taxes: { string: number }
    search-query: string
  user-info:
    direct-user-request: boolean
    ip-address: string
    user-agent: string
    user-id: string
    visitor-id: string

can be set completely with the following arguments which are assumed to be executed in the given order. Note how the cursor position is adjusted to the respective structures, allowing simple field names to be used most of the time.

  • -r .event-detail experiment-ids=accusam
    • Optional. A list of identifiers for the independent experiment groups this user event belongs to. This is used to distinguish between user events associated with different experiment setups (e.g. using Recommendation Engine system, using different recommendation models).
    • Each invocation of this argument appends the given value to the array.
  • page-view-id=voluptua.
    • Optional. A unique id of a web page view. This should be kept the same for all user events triggered from the same pageview. For example, an item detail page view could trigger multiple events as the user is browsing the page. The pageViewId property should be kept the same for all these events so that they can be grouped together properly. This pageViewId will be automatically generated if using the JavaScript pixel.
  • recommendation-token=dolore
    • Optional. Recommendation token included in the recommendation prediction response. This field enables accurate attribution of recommendation model performance. This token enables us to accurately attribute page view or purchase back to the event and the particular predict response containing this clicked/purchased item. If user clicks on product K in the recommendation results, pass the PredictResponse.recommendationToken property as a url parameter to product K's page. When recording events on product K's page, log the PredictResponse.recommendation_token to this field. Optional, but highly encouraged for user events that are the result of a recommendation prediction query.
  • referrer-uri=dolore
    • Optional. The referrer url of the current page. When using the JavaScript pixel, this value is filled in automatically.
  • uri=dolore

    • Optional. Complete url (window.location.href) of the user's current page. When using the JavaScript pixel, this value is filled in automatically. Maximum length 5KB.
  • .. event-source=voluptua.

    • Optional. This field should not be set when using JavaScript pixel or the Recommendations AI Tag. Defaults to EVENT_SOURCE_UNSPECIFIED.
  • event-time=amet.
    • Optional. Only required for ImportUserEvents method. Timestamp of user event created.
  • event-type=ea
    • Required. User event type. Allowed values are: * add-to-cart Products being added to cart. * add-to-list Items being added to a list (shopping list, favorites etc). * category-page-view Special pages such as sale or promotion pages viewed. * checkout-start User starting a checkout process. * detail-page-view Products detail page viewed. * home-page-view Homepage viewed. * page-visit Generic page visits not included in the event types above. * purchase-complete User finishing a purchase. * refund Purchased items being refunded or returned. * remove-from-cart Products being removed from cart. * remove-from-list Items being removed from a list. * search Product search. * shopping-cart-page-view User viewing a shopping cart. * impression List of items displayed. Used by Google Tag Manager.
  • product-event-detail cart-id=sadipscing
    • Optional. The id or name of the associated shopping cart. This id is used to associate multiple items added or present in the cart before purchase. This can only be set for add-to-cart, remove-from-cart, checkout-start, purchase-complete, or shopping-cart-page-view events.
  • list-id=lorem
    • Required for add-to-list and remove-from-list events. The id or name of the list that the item is being added to or removed from. Other event types should not set this field.
  • purchase-transaction costs=key=0.4946595631810975
    • Optional. All the costs associated with the product. These can be manufacturing costs, shipping expenses not borne by the end user, or any other costs. Total product cost such that profit = revenue - (sum(taxes) + sum(costs)) If product_cost is not set, then profit = revenue - tax - shipping - sum(CatalogItem.costs). If CatalogItem.cost is not specified for one of the items, CatalogItem.cost based profit cannot be calculated for this Transaction.
    • the value will be associated with the given key
  • currency-code=est
    • Required. Currency code. Use three-character ISO-4217 code. This field is not required if the event type is refund.
  • id=at
    • Optional. The transaction ID with a length limit of 128 bytes.
  • revenue=0.4551855025693473
    • Required. Total revenue or grand total associated with the transaction. This value include shipping, tax, or other adjustments to total revenue that you want to include as part of your revenue calculations. This field is not required if the event type is refund.
  • taxes=key=0.8987894283575105

    • Optional. All the taxes associated with the transaction.
    • the value will be associated with the given key
  • .. search-query=et

    • At least one of search_query or page_categories is required for search events. Other event types should not set this field. The user's search query as UTF-8 encoded text with a length limit of 5 KiB.
  • ..user-info direct-user-request=true

    • Optional. Indicates if the request is made directly from the end user in which case the user_agent and ip_address fields can be populated from the HTTP request. This should not be set when using the javascript pixel. This flag should be set only if the API request is made directly from the end user such as a mobile app (and not if a gateway or a server is processing and pushing the user events).
  • ip-address=aliquyam
    • Optional. IP address of the user. This could be either IPv4 (e.g. 104.133.9.80) or IPv6 (e.g. 2001:0db8:85a3:0000:0000:8a2e:0370:7334). This should not be set when using the javascript pixel or if direct_user_request is set. Used to extract location information for personalization.
  • user-agent=ipsum
    • Optional. User agent as included in the HTTP header. UTF-8 encoded string with a length limit of 1 KiB. This should not be set when using the JavaScript pixel or if directUserRequest is set.
  • user-id=et
    • Optional. Unique identifier for logged-in user with a length limit of 128 bytes. Required only for logged-in users. Don't set for anonymous users. Don't set the field to the same fixed ID for different users. This mixes the event history of those users together, which results in degraded model quality.
  • visitor-id=sanctus
    • Required. A unique identifier for tracking visitors with a length limit of 128 bytes. For example, this could be implemented with an HTTP cookie, which should be able to uniquely identify a visitor on a single device. This unique identifier should not change if the visitor logs in or out of the website. Maximum length 128 bytes. Cannot be empty. Don't set the field to the same fixed ID for different users. This mixes the event history of those users together, which results in degraded model quality.

About Cursors

The cursor position is key to comfortably set complex nested structures. The following rules apply:

  • The cursor position is always set relative to the current one, unless the field name starts with the . character. Fields can be nested such as in -r f.s.o .
  • The cursor position is set relative to the top-level structure if it starts with ., e.g. -r .s.s
  • You can also set nested fields without setting the cursor explicitly. For example, to set a value relative to the current cursor position, you would specify -r struct.sub_struct=bar.
  • You can move the cursor one level up by using ... Each additional . moves it up one additional level. E.g. ... would go three levels up.

Optional Output Flags

The method's return value a JSON encoded structure, which will be written to standard output by default.

  • -o out
    • out specifies the destination to which to write the server's result to. It will be a JSON-encoded structure. The destination may be - to indicate standard output, or a filepath that is to contain the received bytes. If unset, it defaults to standard output.

Optional General Properties

The following properties can configure any call, and are not specific to this method.

  • -p $-xgafv=string

    • V1 error format.
  • -p access-token=string

    • OAuth access token.
  • -p alt=string

    • Data format for response.
  • -p callback=string

    • JSONP
  • -p fields=string

    • Selector specifying which fields to include in a partial response.
  • -p key=string

    • API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
  • -p oauth-token=string

    • OAuth 2.0 token for the current user.
  • -p pretty-print=boolean

    • Returns response with indentations and line breaks.
  • -p quota-user=string

    • Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
  • -p upload-type=string

    • Legacy upload protocol for media (e.g. "media", "multipart").
  • -p upload-protocol=string

    • Upload protocol for media (e.g. "raw", "multipart").