> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-rust-sdk.md). # Rust Detailed technical documentation on using RudderStack’s Rust SDK to send events to various destinations. The **RudderStack Rust SDK** lets you track your customer event data from your Rust applications and send it to your specified destinations via RudderStack. Check out the [**GitHub codebase**](https://github.com/rudderlabs/rudder-sdk-rust) to get a more hands-on understanding of the SDK. [![Github Badge](https://img.shields.io/crates/v/rudderanalytics.svg)](https://crates.io/crates/rudderanalytics) ## SDK setup requirements To set up the RudderStack Rust SDK, the following prerequisites must be met: * You will need to set up a [**RudderStack account**](https://app.rudderstack.com). * Once signed up, set up a Rust source in the dashboard. For more information, follow [**this guide**](https://www.rudderstack.com/docs/rudderstack-cloud/sources/#adding-a-source). You should then see a **Write Key** for this source, as shown below: ![Rust source write key](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-b6b57e352829f4cac9f984da38368bbaa722d546%2Frust-sdk-1.png?alt=media) * You will also need a data plane URL. Follow [**this section**](https://rudderstack.com/docs/rudderstack-open-source/installing-and-setting-up-rudderstack/#what-is-a-data-plane-url-where-do-i-get-it) for more information on the data plane URL and where to get it. ## Installing the Rust SDK To install the Rust SDK, simply add its crate as a project dependency. Add the following line to your `Cargo.toml` file: ```rust rudderanalytics = "1.0.0" ``` ## Initializing the RudderStack client To initialize the RudderStack client, run the following code snippet: ```rust use rudderanalytics::client::RudderAnalytics; let rudder_analytics = RudderAnalytics::load( "".to_string(), "".to_string() ); ``` Once the RudderStack client is initialized, you can use it to send your customer events. ## Sending events from the RudderStack client The Rust SDK supports the following events: * Identify * Track * Page * Group * Screen * Alias * Batch For more information on each of calls, refer to the [**RudderStack Events Specification**](https://rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/) guide. RudderStack does not store the user state in any of the server-side SDKs. Unlike the client-side SDKs that deal with only a single user at a given time, the server-side SDKs deal with multiple users simultaneously. Therefore, for any of the calls supported by the Rust SDK, you need to specify either the `user_id` or `anonymous_id` every time. ## Identify The `identify` call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc. A sample `identify` call is as shown: ```rust use rudderanalytics::message::{ Identify, Message }; rudder_analytics .send(Message::Identify(Identify { user_id: Some("sample_user_id".to_string()), traits: Some(json!({ "name": "Test User", "email": "test@user.com", })), ..Default::default() })) .expect("Identify call failed to send data to RudderStack"); ``` ### Identify parameters The following table describes the different `identify` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | -------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | String | Optional, if `anonymous_id` is already set. | Unique user identifier in your database. | | `anonymous_id` | String | Optional | Sets an identifier for cases when there is no unique user identifier. Either `user_id` or `anonymous_id` is required. | | `traits` | Object | Optional | Dictionary of the traits associated with the user, such as name, email, etc. | | `original_timestamp` | DateTime | Optional | The timestamp of the event's occurrence as specified by the user, in ISO 8601 format. If not explicitly specified, the SDK appends the timestamp of the event's receipt. | | `context` | Object | Optional | Dictionary of information providing context about a message. It is not directly related to the API call. | | `integrations` | Object | Optional | Dictionary containing the destinations to be enabled or disabled. | ## Track The `track` call lets you record the user actions along with their associated properties. Each user action is called an **event**. A sample `track` call is as shown: ```rust use rudderanalytics::message::{ Track, Message }; rudder_analytics .send(Message::Track(Track { user_id: Some("sample_user_id".to_string()), event: "Test Event".to_owned(), properties: Some(json!({ "some property": "some value", "some other property": "some other value", })), ..Default::default() })) .expect("Track call failed to send data to RudderStack"); ``` ### Track parameters The following table describes the different `track` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | -------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | String | Optional, if `anonymous_id` is already set. | Unique user identifier in your database. | | `anonymous_id` | String | Optional | Sets an identifier for cases when there is no unique user identifier. Either `user_id` or `anonymous_id` is required. | | `event` | String | Required | Name of the event, i.e. the action performed by the user. | | `properties` | Object | Optional | Dictionary of the properties associated with the event. | | `original_timestamp` | DateTime | Optional | The timestamp of the event's occurrence as specified by the user, in ISO 8601 format. If not explicitly specified, the SDK appends the timestamp of the event's receipt. | | `context` | Object | Optional | Dictionary of information providing context about a message. It is not directly related to the API call. | | `integrations` | Object | Optional | Dictionary containing the destinations to be enabled or disabled. | ## Page The `page` call allows you to record the page views on your website along with the other relevant information about the viewed page. We recommend calling `page` at least once every page load. A sample `page` call is as shown: ```rust use rudderanalytics::message::{ Page, Message }; rudder_analytics .send(Message::Page(Page { user_id: Some("sample_user_id".to_string()), name: "Cart viewed".to_owned(), properties: Some(json!({ "some property": "some value", "some other property": "some other value", })), ..Default::default() })) .expect("Page call failed to send data to RudderStack"); ``` ### Page parameters The following table describes the different `page` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | -------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | String | Optional, if `anonymous_id` is already set. | Unique user identifier in your database. | | `anonymous_id` | String | Optional | Sets an identifier for cases when there is no unique user identifier. Either `user_id` or `anonymous_id` is required. | | `name` | String | Required | Name of the viewed page. | | `properties` | Object | Optional | Dictionary of the properties associated with the page view event. | | `original_timestamp` | DateTime | Optional | The timestamp of the event's occurrence as specified by the user, in ISO 8601 format. If not explicitly specified, the SDK appends the timestamp of the event's receipt. | | `context` | Object | Optional | Dictionary of information providing context about a message. It is not directly related to the API call. | | `integrations` | Object | Optional | Dictionary containing the destinations to be enabled or disabled. | ## Screen The `screen` method lets you record whenever the user views their mobile screen, along with any additional relevant information about the screen. ``` The screen call is the mobile equivalent of the page call. ``` A sample `screen` call is shown below: ```rust use rudderanalytics::message::{ Screen, Message }; rudder_analytics .send(Message::Screen(Screen { user_id: Some("sample_user_id".to_string()), name: "sample_screen".to_owned(), properties: Some(json!({ "some property": "some value", "some other property": "some other value", })), ..Default::default() })) .expect("Screen call failed to send data to RudderStack"); ``` ### Screen parameters The following table describes the different `page` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | -------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | String | Optional, if `anonymous_id` is already set. | Unique user identifier in your database. | | `anonymous_id` | String | Optional | Sets an identifier for cases when there is no unique user identifier. Either `user_id` or `anonymous_id` is required. | | `name` | String | Required | Name of the viewed screen. | | `properties` | Object | Optional | Dictionary of the properties associated with the screen view event. | | `original_timestamp` | DateTime | Optional | The timestamp of the event's occurrence as specified by the user, in ISO 8601 format. If not explicitly specified, the SDK appends the timestamp of the event's receipt. | | `context` | Object | Optional | Dictionary of information providing context about a message. It is not directly related to the API call. | | `integrations` | Object | Optional | Dictionary containing the destinations to be enabled or disabled. | ## Group The `group` call lets you associate an identified user to a group - either a company, project or a team and record any custom traits or properties associated with that group. ``` An identified user can be in more than one group. ``` A sample `group` call is as shown: ```rust use rudderanalytics::message::{ Group, Message }; rudder_analytics .send(Message::Group(Group { user_id: Some("sample_user_id".to_string()), group_id: "sample_group_id".to_owned(), traits: Some(json!({ "some property": "some value", "some other property": "some other value", })), ..Default::default() })) .expect("Group call failed to send data to RudderStack"); ``` ### Group parameters The following table describes the different `group` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | -------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | String | Optional, if `anonymous_id` is already set. | Unique user identifier in your database. | | `anonymous_id` | String | Optional | Sets an identifier for cases when there is no unique user identifier. Either `user_id` or `anonymous_id` is required. | | `group_id` | String | Required | Unique identifier of the group in your database. | | `traits` | Object | Optional | Dictionary of the traits associated with the group. | | `original_timestamp` | DateTime | Optional | The timestamp of the event's occurrence as specified by the user, in ISO 8601 format. If not explicitly specified, the SDK appends the timestamp of the event's receipt. | | `context` | Object | Optional | Dictionary of information providing context about a message. It is not directly related to the API call. | | `integrations` | Object | Optional | Dictionary containing the destinations to be enabled or disabled. | ## Alias The `alias` call lets you merge different identities of a known user. ``` alias is an advanced method that lets you change the tracked user's ID explicitly. This method is useful when managing identities for some of the downstream destinations. ``` The following destinations support the `alias` call: * [MoEngage](https://rudderstack.com/docs/destinations/marketing/moengage/) * [Kissmetrics](https://rudderstack.com/docs/destinations/analytics/kissmetrics/) * [Amplitude](https://rudderstack.com/docs/destinations/analytics/amplitude/) (only supported by the [JavaScript SDK ](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk/)via [cloud mode ](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/#cloud-mode)) * [Mixpanel](https://rudderstack.com/docs/destinations/analytics/mixpanel/) A sample `alias` call is shown below: ```rust use rudderanalytics::message::{ Alias, Message }; rudder_analytics .send(Message::Alias(Alias { user_id: Some("sample_user_id".to_string()), previous_id: "sample_previous_user_id".to_owned(), traits: Some(json!({ "some property": "some value", "some other property": "some other value", })), ..Default::default() })) .expect("Alias call failed to send data to RudderStack"); ``` ### Alias parameters The following table describes the different `alias` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | -------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `user_id` | String | Required | Unique user identifier in your database. | | `previous_id` | String | Required | The user's previous identifier. | | `traits` | Object | Optional | Dictionary of the traits associated with the user, such as name, email, etc. | | `original_timestamp` | DateTime | Optional | The timestamp of the event's occurrence as specified by the user, in ISO 8601 format. If not explicitly specified, the SDK appends the timestamp of the event's receipt. | | `context` | Object | Optional | Dictionary of information providing context about a message. It is not directly related to the API call. | | `integrations` | Object | Optional | Dictionary containing the destinations to be enabled or disabled. | ## Batch The `batch` call lets you send multiple user events(of type `identify`, `track`, `page`, `screen`, `group`, and `alias`) in one call. The `batch` call accepts a maximum call size of 4 MB. A sample `batch` call is as shown: ```rust use rudderanalytics::message::{ Batch, Message, BatchMessage }; rudder_analytics .send(Message::Batch(Batch { batch: vec![ BatchMessage::Identify(Identify { user_id: Some("foo".to_string()), traits: Some(json!({})), ..Default::default() }), BatchMessage::Track(Track { user_id: Some("bar".to_string()), event: "Bar".to_owned(), properties: Some(json!({})), ..Default::default() }), BatchMessage::Track(Track { user_id: Some("baz".to_string()), event: "Baz".to_owned(), properties: Some(json!({})), ..Default::default() }), ], context: Some(json!({ "foo": "bar", })), ..Default::default() })) .expect("Batch call failed to send data to Rudderstack"); ``` ### Batch parameters The following table describes the different `batch` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | -------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `batch` | Vector | Required | Contains one or more event calls of type `identify`/ `track`/ `page`/ `screen`/ `group`/ `alias`. | | `context` | Object | Optional | Dictionary of information providing context about a message. It is not directly related to the API call. | | `integrations` | Object | Optional | Dictionary containing the destinations to be enabled or disabled. | | `original_timestamp` | DateTime | Optional | The timestamp of the event's occurrence as specified by the user, in ISO 8601 format. If not explicitly specified, the SDK appends the timestamp of the event's receipt. | ## Integrations options The structure of the `integrations` option is as follows: ```rust integrations: { All: boolean, // Defaults to true : boolean, : boolean, ... } ``` The following table describes all the `integrations` parameters in detail: | **Field** | **Type** | **Presence** | **Description** | | --------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `All` | Boolean | Optional | Corresponds to all the destinations to which the event is to be sent. Defaults to true. `All: false` instructs RudderStack to not send the event data to any destinations by default. | | `` | Boolean | Optional | Name of the specific destination to which the event should be sent/not sent, depending on the Boolean value assigned to it. | ## Contact us For more information on the Rust SDK, you can [**contact us**](mailto:docs@rudderstack.com) or start a conversation in our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community) community. In case you come across any issues while using this SDK, feel free to start a new issue on our [**GitHub repository**](https://github.com/rudderlabs/rudder-sdk-rust).