plausible_rs/api/event/
event_payload_builder.rs

1use crate::{EventPayload, PropValue};
2use std::collections::HashMap;
3
4/// Request body parameters for the 'POST /api/event' API.
5///
6/// This is a Builder for `EventPayload`.
7#[derive(Debug, Clone)]
8pub struct EventPayloadBuilder {
9    /// Domain name of the site in Plausible.
10    ///
11    /// This is the domain name you used when you added your site to your Plausible account.
12    /// It doesn't need to be an actual domain name, so when adding your mobile app to Plausible,
13    /// you could insert the mobile app name in the domain name field
14    pub domain: String,
15
16    /// Name of the event.
17    ///
18    /// Can specify `pageview` which is a special type of event in Plausible.
19    /// All other names will be treated as custom events.
20    pub name: String,
21
22    /// URL of the page where the event was triggered.
23    ///
24    /// If the URL contains UTM parameters, they will be extracted and stored.
25    /// When using the script, this is set to window.location.href.
26    ///
27    /// The URL parameter will feel strange in a mobile app but you can manufacture something that
28    /// looks like a web URL. If you name your mobile app screens like page URLs, Plausible will
29    /// know how to handle it.
30    /// So for example, on your login screen you could send something like:
31    ///
32    /// ```text
33    /// event: pageview
34    /// url: app://localhost/login
35    /// ```
36    ///
37    /// The pathname (/login) is what will be shown as the page value in the Plausible dashboard.
38    pub url: String,
39
40    /// Referrer for this event.
41    ///
42    /// When using the standard tracker script, this is set to `document.referrer`.
43    ///
44    /// Referrer values are processed heavily for better usability.
45    /// Consider referrer URLS like `m.facebook.com/some-path` and `facebook.com/some-other-path`.
46    /// It's intuitive to think of both of these as coming from a single source: Facebook.
47    /// In the first example the `referrer` value would be split into `visit:source == Facebook`
48    /// and `visit:referrer == m.facebook.com/some-path`.
49    ///
50    /// Plausible uses the open source [referer-parser](https://github.com/snowplow-referer-parser/referer-parser)
51    /// database to parse referrers and assign these source categories.
52    ///
53    /// When no match has been found, the value of the referrer field will be parsed as an URL.
54    /// The hostname will be used as the `visit:source` and the full URL as the `visit:referrer`.
55    /// So if you send `https://some.domain.com/example-path`, it will be parsed as follows:
56    /// `visit:source == some.domain.com` `visit:referrer == some.domain.com/example-path`.
57    pub referrer: Option<String>,
58
59    /// Width of the screen.
60    ///
61    /// When using the script, this is set to `window.innerWidth`.
62    pub screen_width: Option<usize>,
63
64    /// Custom properties for the event.
65    ///
66    /// See: <https://plausible.io/docs/custom-event-goals#using-custom-props>
67    ///
68    /// Custom properties only accepts scalar values such as strings, numbers and booleans.
69    /// Data structures such as objects, arrays etc. aren't accepted.
70    pub props: Option<HashMap<String, PropValue>>,
71}
72
73impl EventPayloadBuilder {
74    #[must_use]
75    pub const fn new(domain: String, name: String, url: String) -> Self {
76        Self {
77            domain,
78            name,
79            url,
80            referrer: None,
81            screen_width: None,
82            props: None,
83        }
84    }
85
86    pub fn referrer(&mut self, referrer: String) -> &mut Self {
87        self.referrer = Some(referrer);
88        self
89    }
90
91    pub fn screen_width(&mut self, screen_width: usize) -> &mut Self {
92        self.screen_width = Some(screen_width);
93        self
94    }
95
96    pub fn props(&mut self, props: HashMap<String, PropValue>) -> &mut Self {
97        self.props = Some(props);
98        self
99    }
100
101    #[must_use]
102    pub fn build(&self) -> EventPayload {
103        EventPayload::new(
104            self.domain.clone(),
105            self.name.clone(),
106            self.url.clone(),
107            self.referrer.clone(),
108            self.screen_width,
109            self.props.clone(),
110        )
111    }
112}
plausible_rs/api/event/event_payload_builder.rs

plausible_rs/api/event/
event_payload_builder.rs
