nearby/fastpair/proto/data.proto

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package nearby.fastpair.proto;

import "third_party/nearby/fastpair/proto/enum.proto";
import "third_party/nearby/fastpair/proto/fast_pair_string.proto";

option java_multiple_files = true;

// Information about Fast Pair. This will either contain a Fast Pair device
// or an opt in status.
message FastPairInfo {
  oneof info {
    OptInStatus opt_in_status = 1;
    FastPairDevice device = 2;
  }
}

// A device that has been Fast Paired with.
message FastPairDevice {
  // The account key which was written to the device after pairing completed.
  bytes account_key = 1;

  // The stored discovery item which represents the notification that should be
  // associated with the device. Note, this is stored as a raw byte array
  // instead of StoredDiscoveryItem because icing only supports proto lite and
  // StoredDiscoveryItem is handed around as a nano proto in implementation,
  // which are not compatible with each other.
  bytes discovery_item_bytes = 3;

  // SHA256 of "account key + headset's public address", this is used to
  // identify the paired headset. Because of adding account key to generate the
  // hash value, it makes the information anonymous, even for the same headset,
  // different accounts have different values.
  bytes sha256_account_key_public_address = 4;

  // Deprecated fields.
  reserved 2;
}

// Additional images for True Wireless Fast Pair devices.
message TrueWirelessHeadsetImages {
  // Image URL for the left bud.
  optional string left_bud_url = 1;

  // Image URL for the right bud.
  optional string right_bud_url = 2;

  // Image URL for the case.
  optional string case_url = 3;
}

// Relevance indicates how relevant the item is to the user.
message Relevance {
  // Whether the item is good, ok, poor, etc. Corresponds to levels found in
  // the Discoverer Notification Policy Worksheet:
  // https://docs.google.com/a/google.com/spreadsheets/d/1atc1-RNLb7fAGvGdWXlh86Qy2IY9T_dj2v4gFUhdPF0/edit?usp=sharing
  Evaluation evaluation = 1;

  // To get this relevance, the item can be at most this far away.
  // Note: Supported in v11+.
  // TODO(jfarfel): Replace with Targeting.
  optional double max_distance = 2;
}

message StoredRelevance {
  Relevance relevance = 1;

  // The last time that this relevance passed targeting. A relevance with no
  // targeting always passes. Null if it failed, or we haven't checked yet.
  optional int64 targeting_true_millis = 2;
}

// Additional information relevant only for Fast Pair devices.
message FastPairInformation {
  // When true, Fast Pair will only create a bond with the device and not
  // attempt to connect any profiles (for example, A2DP or HFP).
  // TODO(b/128545971): Transition this to a feature.
  optional bool data_only_connection = 1;

  // Additional images that are attached specifically for true wireless Fast
  // Pair devices.
  optional TrueWirelessHeadsetImages true_wireless_images = 3;
}

// Data for a DiscoveryItem created from server response and client scan result.
// Only caching original data from scan result, server response, timestamps
// and user actions. Do not save generated data in this object.
// Next ID: 51
message StoredDiscoveryItem {
  enum State {
    // Default unknown state.
    STATE_UNKNOWN = 0;

    // The item is normal.
    STATE_ENABLED = 1;

    // The item has been muted by user.
    STATE_MUTED = 2;

    // The item has been disabled by us (likely temporarily).
    STATE_DISABLED_BY_SYSTEM = 3;
  }

  // The status of the item.
  enum DebugMessageCategory {
    // Default unknown state.
    STATUS_UNKNOWN = 0;

    // The item is valid and visible in notification.
    STATUS_VALID_NOTIFICATION = 1;

    // The item made it to list but not to notification.
    STATUS_VALID_LIST_VIEW = 2;

    // The item is filtered out on client. Never made it to list view.
    STATUS_DISABLED_BY_CLIENT = 3;

    // The item is filtered out by server. Never made it to client.
    STATUS_DISABLED_BY_SERVER = 4;
  }

  enum ExperienceType {
    EXPERIENCE_UNKNOWN = 0;
    EXPERIENCE_GOOD = 1;
    EXPERIENCE_BAD = 2;
  }

  // REQUIRED
  // Offline item: unique ID generated on client.
  // Online item: unique ID generated on server.
  optional string id = 1;

  // REQUIRED
  optional NearbyType type = 2;

  // REQUIRED
  // The most recent all upper case mac associated with this item.
  // (Mac-to-DiscoveryItem is a many-to-many relationship)
  optional string mac_address = 4;

  // REQUIRED
  optional string action_url = 5;

  // The bluetooth device name from advertisment
  optional string device_name = 6;

  // REQUIRED
  // Item's title
  optional string title = 7;

  // Item's description.
  optional string description = 8;

  // The URL for display
  optional string display_url = 9;

  // REQUIRED
  // Client timestamp when the beacon was last observed in BLE scan.
  optional int64 last_observation_timestamp_millis = 10;

  // REQUIRED
  // Client timestamp when the beacon was first observed in BLE scan.
  optional int64 first_observation_timestamp_millis = 11;

  // REQUIRED
  // Item's current state. e.g. if the item is blocked.
  optional State state = 17;

  // The resolved url type for the action_url.
  optional ResolvedUrlType action_url_type = 19;

  // The timestamp when the user is redirected to Play Store after clicking on
  // the item.
  optional int64 pending_app_install_timestamp_millis = 20;

  // Beacon's RSSI value
  optional int32 rssi = 22;

  // Beacon's tx power
  optional int32 tx_power = 23;

  // Human readable name of the app designated to open the uri
  // Used in the second line of the notification, "Open in {} app"
  optional string app_name = 25;

  // ID used for associating several DiscoveryItems.  These items may be
  // visually displayed together.
  optional string group_id = 26;

  // The timestamp when the attachment was created on PBS server. In case there
  // are duplicate
  // items with the same scanId/groupID, only show the one with the latest
  // timestamp.
  optional int64 attachment_creation_sec = 28;

  // Package name of the App that owns this item.
  optional string package_name = 30;

  // The average star rating of the app.
  optional float star_rating = 31;

  // The "feature" graphic image url used for large sized list view entries.
  optional string feature_graphic_url = 32;

  // TriggerId identifies the trigger/beacon that is attached with a message.
  // It's generated from server for online messages to synchronize formatting
  // across client versions.
  // Example:
  // * BLE_UID: 3||deadbeef
  // * BLE_URL: http://trigger.id
  // See go/discovery-store-message-and-trigger-id for more details.
  optional string trigger_id = 34;

  // Bytes of item icon in PNG format displayed in Discovery item list.
  optional bytes icon_png = 36;

  // How relevant the message is to the user. May be used by the client to
  // determine how to display the NearbyItem. >1 relevance makes sense only if
  // each has targeting (e.g., a maximum distance threshold). In that case, the
  // item's relevance is the maximum one where the targeting is satisfied.
  repeated StoredRelevance stored_relevances = 40;

  // A FIFE URL of the item icon displayed in Discovery item list.
  optional string icon_fife_url = 49;

  // Message written to bugreport for 3P developers.(No sensitive info)
  // null if the item is valid
  optional string debug_message = 37;

  // Weather the item is filtered out on server.
  optional DebugMessageCategory debug_category = 38;

  // Client timestamp when the trigger (e.g. beacon) was last lost (e.g. when
  // Messages told us the beacon's no longer nearby).
  optional int64 lost_millis = 41;

  // The kind of expereince the user last had with this (e.g. if they dismissed
  // the notification, that's bad; but if they tapped it, that's good).
  optional ExperienceType last_user_experience = 42;

  // The most recent BLE advertisement related to this item.
  optional bytes ble_record_bytes = 43;

  // An ID generated on the server to uniquely identify content.
  optional string entity_id = 44;

  // See equivalent field in NearbyItem.
  optional bytes authentication_public_key_secp256r1 = 45;

  // See equivalent field in NearbyItem.
  optional FastPairInformation fast_pair_information = 46;

  // Fast pair strings
  optional FastPairStrings fast_pair_strings = 48;

  // The time of the account key's association.
  // We use device local time for this field, so could be inaccurate.
  optional int64 account_key_association_local_timestamp_ms = 50;

  // Deprecated fields.
  reserved 3, 12, 13, 14, 15, 16, 18, 21, 24, 27, 33, 35, 39;
}