Struct plausible_rs::EventPayloadBuilder

pub struct EventPayloadBuilder {
    pub domain: String,
    pub name: String,
    pub url: String,
    pub referrer: Option<String>,
    pub screen_width: Option<usize>,
    pub props: Option<HashMap<String, PropValue>>,
}

Request body parameters for the ‘POST /api/event’ API.

This is a Builder for EventPayload.

Fields

domain: String

Domain name of the site in Plausible.

This is the domain name you used when you added your site to your Plausible account. It doesn’t need to be an actual domain name, so when adding your mobile app to Plausible, you could insert the mobile app name in the domain name field

name: String

Name of the event.

Can specify pageview which is a special type of event in Plausible. All other names will be treated as custom events.

url: String

URL of the page where the event was triggered.

If the URL contains UTM parameters, they will be extracted and stored. When using the script, this is set to window.location.href.

The URL parameter will feel strange in a mobile app but you can manufacture something that looks like a web URL. If you name your mobile app screens like page URLs, Plausible will know how to handle it. So for example, on your login screen you could send something like:

event: pageview
url: app://localhost/login

The pathname (/login) is what will be shown as the page value in the Plausible dashboard.

referrer: Option<String>

Referrer for this event.

When using the standard tracker script, this is set to document.referrer.

Referrer values are processed heavily for better usability. Consider referrer URLS like m.facebook.com/some-path and facebook.com/some-other-path. It’s intuitive to think of both of these as coming from a single source: Facebook. In the first example the referrer value would be split into visit:source == Facebook and visit:referrer == m.facebook.com/some-path.

Plausible uses the open source referer-parser database to parse referrers and assign these source categories.

When no match has been found, the value of the referrer field will be parsed as an URL. The hostname will be used as the visit:source and the full URL as the visit:referrer. So if you send https://some.domain.com/example-path, it will be parsed as follows: visit:source == some.domain.com visit:referrer == some.domain.com/example-path.

screen_width: Option<usize>

Width of the screen.

When using the script, this is set to window.innerWidth.

props: Option<HashMap<String, PropValue>>

Custom properties for the event.

See: https://plausible.io/docs/custom-event-goals#using-custom-props

Custom properties only accepts scalar values such as strings, numbers and booleans. Data structures such as objects, arrays etc. aren’t accepted.

Implementations

impl EventPayloadBuilder

pub const fn new(domain: String, name: String, url: String) -> Self

pub fn referrer(&mut self, referrer: String) -> &mut Self

Examples found in repository

examples/event.rs (line 19)

async fn main() {
    let domain: String = env::var("PLAUSIBLE_DOMAIN")
        .expect("set env var `PLAUSIBLE_DOMAIN` to name of site in Plausible");

    Plausible::new().event(
        EventHeaders::new(
            String::from("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"),
            String::from("127.0.0.1")
        ),
        EventPayload::builder(
            domain.clone(),
            PAGEVIEW_EVENT.to_string(),
            format!("https://{}/test", domain))
            .referrer(String::from("https://www.toddgriffin.me/"))
            .screen_width(2560)
            .props(HashMap::from([(
                String::from("author"),
                PropValue::from(String::from("Todd Everett Griffin")),
            )]))
            .build()
        ).await.unwrap();
}

pub fn screen_width(&mut self, screen_width: usize) -> &mut Self

Examples found in repository

examples/event.rs (line 20)

async fn main() {
    let domain: String = env::var("PLAUSIBLE_DOMAIN")
        .expect("set env var `PLAUSIBLE_DOMAIN` to name of site in Plausible");

    Plausible::new().event(
        EventHeaders::new(
            String::from("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"),
            String::from("127.0.0.1")
        ),
        EventPayload::builder(
            domain.clone(),
            PAGEVIEW_EVENT.to_string(),
            format!("https://{}/test", domain))
            .referrer(String::from("https://www.toddgriffin.me/"))
            .screen_width(2560)
            .props(HashMap::from([(
                String::from("author"),
                PropValue::from(String::from("Todd Everett Griffin")),
            )]))
            .build()
        ).await.unwrap();
}

pub fn props(&mut self, props: HashMap<String, PropValue>) -> &mut Self

Examples found in repository

examples/event.rs (lines 21-24)

async fn main() {
    let domain: String = env::var("PLAUSIBLE_DOMAIN")
        .expect("set env var `PLAUSIBLE_DOMAIN` to name of site in Plausible");

    Plausible::new().event(
        EventHeaders::new(
            String::from("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"),
            String::from("127.0.0.1")
        ),
        EventPayload::builder(
            domain.clone(),
            PAGEVIEW_EVENT.to_string(),
            format!("https://{}/test", domain))
            .referrer(String::from("https://www.toddgriffin.me/"))
            .screen_width(2560)
            .props(HashMap::from([(
                String::from("author"),
                PropValue::from(String::from("Todd Everett Griffin")),
            )]))
            .build()
        ).await.unwrap();
}

pub fn build(&self) -> EventPayload

Examples found in repository

examples/event.rs (line 25)

async fn main() {
    let domain: String = env::var("PLAUSIBLE_DOMAIN")
        .expect("set env var `PLAUSIBLE_DOMAIN` to name of site in Plausible");

    Plausible::new().event(
        EventHeaders::new(
            String::from("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"),
            String::from("127.0.0.1")
        ),
        EventPayload::builder(
            domain.clone(),
            PAGEVIEW_EVENT.to_string(),
            format!("https://{}/test", domain))
            .referrer(String::from("https://www.toddgriffin.me/"))
            .screen_width(2560)
            .props(HashMap::from([(
                String::from("author"),
                PropValue::from(String::from("Todd Everett Griffin")),
            )]))
            .build()
        ).await.unwrap();
}

Trait Implementations

impl Clone for EventPayloadBuilder

fn clone(&self) -> EventPayloadBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EventPayloadBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.