nearby/internal/proto/analytics/fast_pair_log.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 = "proto2";

package nearby.proto.fastpair;

import "third_party/nearby/proto/fast_pair_enums.proto";

option optimize_for = LITE_RUNTIME;
option java_package = "nearby.proto.fastpair";
option java_outer_classname = "FastPairLogProto";

// Logging for go/magic-pair.
//
// Note that each event is logged with a code in NearbyEventCodes.EventCode, as
// the upper level LogEvent.event_code. All FastPair events during the same
// attempt ("tap to pair" through success/fail) have the same
// LogEvent.event_flow_id (only unique per device ID).
//
// Each log event represents the completion of that event. E.g. GATT_CONNECT
// means a GATT connection attempt has completed (successfully or not).
message FastPairLog {
  // The 3-byte identifier for the FastPair device model (in the three
  // least-significant bytes) that the user is pairing with. E.g., if the user
  // is pairing with a pair of "Bose BayWolf Silver" headphones, this would be
  // 0xF00001. Not unique to a particular user or device, only a model.
  // go/magic-pair-model-ids
  optional int32 model_id = 1 [(wireless.android.privacy.collection_basis) = {
    use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
    use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
  }];

  // The current bond state with the target device.
  // third_party/nearby/internal/proto/analytics
  optional nearby.proto.fastpair.FastPairEvent.BondState bond_state = 2
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];

  // If the event is a success, this will be 0 (or unset). Otherwise, nonzero.
  // If this is OTHER_ERROR, more detailed error info may be available in
  // one of the other fields.
  optional nearby.proto.fastpair.FastPairEvent.ErrorCode error_code = 3
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];

  // For events involving GATT operations, this may be present.
  optional GattEvent gatt_event = 4
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];

  // For events during the BR/EDR Handover process, this may be present.
  optional BrEdrHandoverEvent br_edr_handover_event = 5
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];

  // For the CREATE_BOND event, this may be present.
  optional CreateBondEvent bond_event = 6
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];

  // For the CONNECT_PROFILE event, this may be present.
  optional ConnectEvent connect_event = 7
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];

  // The device address of the beacon, after being irreversibly salted and
  // hashed. The salt rotates on the client. Used for Fast Pair analytics, to
  // detect false positives.
  optional int64 hashed_salted_device_address = 8 [
    (datapol.semantic_type) = ST_SESSION_ID,
    (wireless.android.privacy.collection_basis) = {
      use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
    }
  ];

  // The duration about how long this event take to finish in millisecond.
  optional int64 duration = 9 [(wireless.android.privacy.collection_basis) = {
    use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
    use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
  }];

  // For the DEVICE_RECOGNIZED event, this may be present.
  optional ProviderInfo provider_info = 10
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
      }];

  // For the WRITE_TO_FOOTPRINTS event, this may be present.
  optional FootprintsInfo footprints_info = 11
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
      }];

  message GattEvent {
    // Error code returned by the OS, e.g. 133 is common.
    optional int32 error_from_os = 1;
  }

  message BrEdrHandoverEvent {
    optional nearby.proto.fastpair.FastPairEvent.BrEdrHandoverErrorCode
        error_code = 1;
  }

  message CreateBondEvent {
    optional nearby.proto.fastpair.FastPairEvent.CreateBondErrorCode
        error_code = 1;

    // Hidden error codes in android.bluetooth.BluetoothDevice
    optional int32 unbond_reason = 2;
  }

  message ConnectEvent {
    optional nearby.proto.fastpair.FastPairEvent.ConnectErrorCode error_code =
        1;

    // The 16-bit UUID (in the two least-significant bytes) for the profile we
    // tried to connect to. E.g. A2DP sink is 0x110B. Not unique to a user or
    // device. Should be one of the values here:
    // https://www.bluetooth.com/specifications/assigned-numbers/service-discovery
    optional int32 profile_uuid = 2;
  }

  message ProviderInfo {
    // The number of account keys stored in the provider.
    optional int32 number_account_keys_on_provider = 1;
  }

  message FootprintsInfo {
    // The number of Fast Pair devices stored on the footprints.
    // It's used to track the growth of Fast Pair users.
    // This value indicates how many headsets owned by a user.
    // If the number of account keys on the footprints is 1, it means this is a
    // new user.
    optional int32 number_devices_on_footprints = 1;
  }

  // e.g. phone, tablet, wearable, tv, pc, auto.
  optional nearby.proto.fastpair.DeviceType device_type = 12
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
        use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
      }];

  // e.g. android, chrome os.
  optional nearby.proto.fastpair.OsType os_type = 13
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
        use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
      }];

  // Active wifi band 2.4g/5g/6g. E.g. 2412, 2437, 5660, 5745...
  optional int32 active_wifi_frequency = 14;

  // Number of connected peripherals
  // -1 if the device can't get the result.
  optional int32 number_connected_peripherals = 15;

  // Whether the current provider is scanned by the offload scanner.
  optional bool is_scanned_by_offload_scanner = 16
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
        use_cases: UC_SERVICE_OR_API_PRODUCT_IMPROVEMENT
      }];

  // For the SECRET_HANDSHAKE event, add more info.
  message KeyBasedPairingInfo {
    // Request flag
    optional uint32 request_flag = 1;
    // Response type
    optional uint32 response_type = 2;
    // Response flag for pairing information
    optional uint32 response_flag = 3;
    // Response device count for pairing
    optional uint32 response_device_count = 4;
  }

  // For the SECRET_HANDSHAKE event, add more info
  optional KeyBasedPairingInfo key_based_pairing_info = 17
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];

  // For the CREATE_BOND event, add bonding transport
  optional uint32 bonding_transport = 18
      [(wireless.android.privacy.collection_basis) = {
        use_cases: UC_SERVICE_OR_API_FUNCTIONAL_DEBUGGING
      }];
}