plausible_rs/api/event/
event_payload.rs

1use crate::{EventPayloadBuilder, PropValue};
2use std::collections::HashMap;
3
4use serde::{Deserialize, Serialize};
5
6/// Request body parameters for the 'POST /api/event' API.
7#[derive(Debug, Clone, Serialize, Deserialize)]
8pub struct EventPayload {
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    #[serde(skip_serializing_if = "Option::is_none")]
58    pub referrer: Option<String>,
59
60    /// Width of the screen.
61    ///
62    /// When using the script, this is set to `window.innerWidth`.
63    #[serde(skip_serializing_if = "Option::is_none")]
64    pub screen_width: Option<usize>,
65
66    /// Custom properties for the event.
67    ///
68    /// See: <https://plausible.io/docs/custom-event-goals#using-custom-props>
69    ///
70    /// Custom properties only accepts scalar values such as strings, numbers and booleans.
71    /// Data structures such as objects, arrays etc. aren't accepted.
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub props: Option<HashMap<String, PropValue>>,
74}
75
76impl EventPayload {
77    #[must_use]
78    pub const fn new(
79        domain: String,
80        name: String,
81        url: String,
82        referrer: Option<String>,
83        screen_width: Option<usize>,
84        props: Option<HashMap<String, PropValue>>,
85    ) -> Self {
86        Self {
87            domain,
88            name,
89            url,
90            referrer,
91            screen_width,
92            props,
93        }
94    }
95
96    #[must_use]
97    pub const fn builder(domain: String, name: String, url: String) -> EventPayloadBuilder {
98        EventPayloadBuilder::new(domain, name, url)
99    }
100}
plausible_rs/api/event/event_payload.rs

plausible_rs/api/event/
event_payload.rs
