components/ntp_snippets/contextual/proto/get_pivots_response.proto

// Copyright 2018 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto2";

option optimize_for = LITE_RUNTIME;

package contextual_suggestions;

message GetPivotsResponse {
  // The suggested followups.
  optional Pivots pivots = 2;
}

// Container for all explore on content data.
message Pivots {
  // Items related to the user's context.
  repeated PivotItem item = 1;

  // The conditions under which auto-peek should be enabled.
  optional AutoPeekConditions auto_peek_conditions = 3;

  // The text to present to the user in the peek.
  optional PeekText peek_text = 4;

  // Information about experiments running on this request.
  repeated ExperimentInfo experiment_info = 5;
}

// One related response.
message PivotItem {
  oneof kind {
    PivotDocument document = 1;
    PivotCluster cluster = 6;
  }
}

// A document related to the source data.
message PivotDocument {
  // A link to the document.
  optional Url url = 1;

  // An image that may be shown next to the document.
  optional Image image = 2;

  // Title of this document.
  optional string title = 3;

  // Snippet summary of this document.
  optional string summary = 4;

  // Human-readable version of the source site's name (e.g. "CNN" instead of
  // "cnn.com").
  optional string site_name = 5;

  // A favicon image, usually related to the site.
  optional Image favicon_image = 6;
}

// A cluster of responses related to the source data. The cluster optionally has
// a label.
message PivotCluster {
  // Label for the cluster.
  optional ClusterLabel label = 1;

  // Ranked items that belong to this cluster.
  repeated PivotItem item = 2;

  // Number of items to show to the user before they expand.
  optional int32 num_items_to_display_pre_expansion = 3 [default = 1];
}

// The label for a cluster of followup items.
message ClusterLabel {
  // Label to display to the user.
  optional string label = 1;
}

message AutoPeekConditions {
  // A measure of confidence that auto-peek should be enabled for this response
  // in the range [0, 1].  In general, if the value is 1.0, auto-peek should be
  // enabled; if 0.0, it shouldn’t; and intermediate values are left to the
  // client to decide.
  optional float confidence = 1 [default = 1.0];

  // The percentage of the page that the user scrolls required for an auto
  // peek to occur. Value should be a decimal between 0 and 1.0.
  // 1.0 represents the entire page's length.
  optional float page_scroll_percentage = 2 [default = 0.0];

  // The minimum time (seconds) the user spends on the page required for
  // auto peek.
  optional float minimum_seconds_on_page = 3 [default = 0.0];

  // The maximum number of auto peeks that we can show for this page.
  // If set to 0, we will never auto peek. Service can set this to a very
  // large number to effectively have unlimited auto peeks.
  optional uint64 maximum_number_of_peeks = 4 [default = 0];
}

message PeekText {
  // Text to display to the user.
  optional string text = 1;
}

message Url {
  optional string raw_url = 1;
}

message Image {
  // The identity of this image.
  optional ImageId id = 1;

  // The underlying source data that encodes the image.
  optional ImageSource source_data = 2;
}

message ImageId {
  // The encrypted document ID of the image, which is a base64-encoded string
  // that can be used to generate image URLs of the form:
  //
  //     "http://www.google.com/images?q=tbn:<encrypted doc id>"
  //
  // For example, the image:
  //
  //     "http://www.google.com/images?q=tbn:e-AB_0zkH08qtM
  //
  // ... has an encrypted doc ID of "e-AB_0zkH08qtM".
  optional string encrypted_docid = 1;
}

// Represents the underlying encoding / source data for an image.
message ImageSource {
  // The raster image representation.
  optional RasterImage raster = 1;
}

// A representation of an image as a collection of pixels at a specific size.
message RasterImage {
  // A URL at which the image may be retrieved. The format of the image
  // is determined by the "Content-Type" of the HTTP response for the URL.
  optional Url url = 2;
}

// Synthetic experiment IDs, which Chrome may log in UMA.
message ExperimentInfo {
  // Name of experiment. A single live-experiment will have one
  // experiment_group_name, and two or more experiment_arm_name's.
  //
  // This corresponds to an experiment group in GWS, and a field trial in Chrome
  // Variations.
  optional string experiment_group_name = 1;

  // Name of experiment arm.
  //
  // This corresponds to an experiment arm in GWS, and a field trial group in
  // Chrome Variations.
  optional string experiment_arm_name = 2;
}