ark-api 0.17.0-pre.15

//! # 📮 Telemetry API
//!
//! This API enables modules to send their own telemetry for tracking user events that happen in the game and module
//! that can be interesting and useful to be able to aggregate and analyze separately to see how users use the module
//!
//! ## Example usage
//!
//! ```rust
//! require_telemetry_api!();
//!
//! ark::telemetry::send_event(
//!    "Thing Happened",
//!    &[("prop1", "value1"), ("another", "value2")],
//!);
//! ```

use crate::ffi::telemetry_v0 as ffi;

/// Identifiers for players, with 0 meaning local player.
pub use ffi::PlayerIdRepr as PlayerId;

#[doc(hidden)]
pub use ffi::API as FFI_API;

/// Send a telemetry event
///
/// Event names should have the format "Object Action". i.e.
/// - _World Loaded_
/// - _Challenge Completed_
/// - _World link Copied_
///
/// Event property keys should be written in `snake_case`. i.e.
/// - `name`
/// - `world_guid`
///
/// The event name and the property key names define a stable schema so should be thoughtfully named
/// and only change if the meaning of the event fully change. They are defined as static strings
/// to help enforce this requirement and reduce the chance of accidentally using a dynamic string and dynamic schema
pub fn send_event(name: &'static str, properties: &[(&'static str, &str)]) {
    let ffi_properties = properties
        .iter()
        .map(|(key, value)| ffi::EventProperty {
            key_ptr: key.as_ptr() as u32,
            key_len: key.len() as u32,
            value_ptr: value.as_ptr() as u32,
            value_len: value.len() as u32,
        })
        .collect::<Vec<_>>();

    ffi::send_event(name, &ffi_properties);
}

/// Send a telemetry event associated with a specific player
///
/// Event names should have the format "Object Action". i.e.
/// - _World Loaded_
/// - _Challenge Completed_
/// - _World link Copied_
///
/// Event property keys should be written in `snake_case`. i.e.
/// - `name`
/// - `world_guid`
///
/// The event name and the property key names define a stable schema so should be thoughtfully named
/// and only change if the meaning of the event fully change. They are defined as static strings
/// to help enforce this requirement and reduce the chance of accidentally using a dynamic string and dynamic schema
pub fn send_event_for_player(
    player_id: PlayerId,
    event_name: &'static str,
    event_properties: &[(&'static str, &str)],
) {
    let ffi_properties = event_properties
        .iter()
        .map(|(key, value)| ffi::EventProperty {
            key_ptr: key.as_ptr() as u32,
            key_len: key.len() as u32,
            value_ptr: value.as_ptr() as u32,
            value_len: value.len() as u32,
        })
        .collect::<Vec<_>>();

    ffi::send_event_for_player(player_id, event_name, &ffi_properties);
}