Getting started overview

Integrating with RudderStack involves a sequence of steps designed to configure data collection and routing. The initial setup focuses on account creation, obtaining necessary authentication credentials, and sending a preliminary event to confirm the integration is operational. RudderStack supports various SDKs for client-side and server-side integration, allowing developers to choose the most appropriate method for their application architecture. This guide outlines the foundational steps required to get data flowing into your RudderStack workspace.

The process generally follows these stages:

  1. Account Creation: Register for a RudderStack account.
  2. Workspace Setup: Create a new workspace, if not already provided.
  3. Source Configuration: Add a new data source within your workspace.
  4. Write Key Retrieval: Obtain the unique Write Key associated with your source.
  5. SDK/API Initialization: Configure the chosen RudderStack SDK or API client with the Write Key.
  6. First Event Transmission: Send a test event to verify data ingestion.
  7. Destination Configuration (Optional but Recommended): Set up a destination to route collected data.

This structured approach ensures that each component is correctly configured before moving to more advanced data governance or transformation features. For a comprehensive understanding of RudderStack's architecture, refer to the RudderStack architecture documentation.

Create an account and get keys

To begin, you must create a RudderStack account. RudderStack offers a free tier that supports up to 500,000 events per month, which is suitable for initial testing and development. After signing up, you will be prompted to create a workspace, which acts as a container for your data sources and destinations.

Account Creation and Workspace Setup

  1. Navigate to the RudderStack signup page.
  2. Complete the registration process using your email or a supported SSO provider.
  3. Once logged in, you will be directed to the RudderStack dashboard. If it's your first time, a default workspace might be created, or you'll be prompted to create one.

Adding a Source and Obtaining a Write Key

A source is where your event data originates. RudderStack supports various source types, including client-side SDKs (e.g., JavaScript, iOS, Android) and server-side SDKs (e.g., Node.js, Python, Go).

  1. From the RudderStack dashboard, click Add Source.
  2. Select the type of source that matches your application (e.g., JavaScript for a web application, Python for a backend service).
  3. Give your source a descriptive name (e.g., MyWebApp-Events).
  4. Click Continue.
  5. RudderStack will generate a unique Write Key for your new source. This key is crucial for authenticating your application when sending data to RudderStack. Copy this key and store it securely, as it functions as an API key for your data stream.
  6. The dashboard will also display the Data Plane URL, which is the endpoint your SDKs will send data to. For most cloud deployments, this URL is shared across your workspace.

Your first request

After setting up your source and obtaining the Write Key, the next step is to send your first event. This example uses the JavaScript SDK, a common choice for web applications. RudderStack provides SDKs for multiple platforms, including Python, Go, and mobile environments.

Using the JavaScript SDK (Web Example)

Insert the following JavaScript snippet into the <head> section of your web page:

<script type="text/javascript">
  !function(){var analytics=window.rudderanalytics=window.rudderanalytics||[];analytics.methods=["load","page","track","identify","alias","group","ready","reset","getAnonymousId","setAnonymousId"];analytics.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);t.unshift(e);analytics.push(t);return analytics}};for(var i=0;i<analytics.methods.length;i++){var key=analytics.methods[i];analytics[key]=analytics.factory(key)}analytics.load("<YOUR_WRITE_KEY>","<YOUR_DATAPLANE_URL>");analytics.page();var r=document.getElementsByTagName("script")[0];var s=document.createElement("script");s.type="text/javascript";s.async=true;s.src="https://cdn.rudderlabs.com/v1.1/rudder-analytics.min.js";r.parentNode.insertBefore(s,r);analytics.track("First Event", {"property": "value"});}()
</script>

Replace:

  • <YOUR_WRITE_KEY> with the Write Key you obtained from your RudderStack source.
  • <YOUR_DATAPLANE_URL> with your specific Data Plane URL (e.g., https://yourworkspace.dataplane.rudderstack.com).

This script initializes the RudderStack SDK, loads the necessary library, calls page() to record a page view, and then calls track() to send a custom event named "First Event" with a property. The track() call is the core method for sending custom event data.

Verifying the Event

After deploying the code, load the web page in your browser. To verify that the event was received by RudderStack:

  1. Navigate back to your source in the RudderStack dashboard.
  2. Go to the Live Events tab.
  3. You should see the "First Event" appear in the live event stream, confirming successful data ingestion.

Using the Python SDK (Server-Side Example)

For server-side applications, you can use one of RudderStack's server-side SDKs. Here's an example using the Python SDK:

import rudderanalytics

rudderanalytics.write_key = '<YOUR_WRITE_KEY>'
rudderanalytics.data_plane_url = '<YOUR_DATAPLANE_URL>'

rudderanalytics.track('First Server Event', {
    'user_id': 'user123',
    'action': 'login',
    'platform': 'backend'
})

print("Event sent successfully!")

Replace:

  • <YOUR_WRITE_KEY> with your Write Key.
  • <YOUR_DATAPLANE_URL> with your Data Plane URL.

Execute this Python script. The event will appear in the Live Events tab for your source in the RudderStack dashboard.

Common next steps

Once you've successfully sent your first event, consider these common next steps to expand your RudderStack implementation:

  1. Configure Destinations: RudderStack allows you to route your collected data to various destinations, such as analytics tools (e.g., Google Analytics, Mixpanel), marketing automation platforms (e.g., HubSpot, Salesforce), data warehouses (e.g., Snowflake, Google BigQuery), or cloud storage (e.g., Amazon S3). Adding a destination is essential for making your data actionable. Refer to the RudderStack Destinations documentation for a list of supported integrations.

  2. Implement Identify Calls: The identify() method is used to associate actions with a specific user and to record their traits (e.g., name, email, subscription status). Implementing identify() calls is crucial for building comprehensive user profiles and enabling personalized experiences. For more details, consult the RudderStack Identify documentation.

  3. Explore Transformations: RudderStack Transformations allow you to modify, filter, or enrich your event data before it reaches its destinations. This feature is useful for data governance, anonymization, and ensuring data quality. You can write custom JavaScript functions to perform these transformations. Learn more about RudderStack Transformations.

  4. Set up Reverse ETL: RudderStack's Reverse ETL feature enables you to move transformed data from your data warehouse back into operational tools (e.g., CRM, marketing platforms). This is valuable for activating your warehouse data. The Reverse ETL documentation provides setup instructions.

  5. Implement Data Governance: RudderStack provides features for data governance, including schema validation and event filtering, to maintain data quality and compliance. Review RudderStack's data governance capabilities to ensure your data adheres to organizational standards and regulatory requirements like GDPR or CCPA. An example of a common data governance practice is to define and enforce a consistent event schema, which helps ensure that data collected across different sources is uniform and usable by downstream systems, as outlined by general event validation best practices.

Troubleshooting the first call

If your first event doesn't appear in the RudderStack Live Events tab, consider the following common issues and troubleshooting steps:

Step What to do Where to check
Write Key Mismatch Ensure the Write Key used in your SDK/API client exactly matches the key displayed for your source in the RudderStack dashboard. Copy-paste errors are common. RudderStack dashboard > Sources > Your Source > Settings
Data Plane URL Incorrect Verify that the Data Plane URL configured in your SDK/API client is correct and accessible. This URL directs your events to your RudderStack instance. RudderStack dashboard > Sources > Your Source > Settings
Network Issues or Ad-Blockers Check your browser's developer console (Network tab) for any failed requests to the Data Plane URL. Ad-blockers or browser extensions might interfere with script loading or network requests. Browser Developer Tools > Network tab
SDK Initialization Errors Look for errors in your browser's developer console (Console tab) or your server-side application logs that indicate issues with the RudderStack SDK initialization. Browser Developer Tools > Console tab, or Server-side application logs
Firewall/Proxy Restrictions If operating in a restricted network environment, ensure that your application or server can access cdn.rudderlabs.com (for SDK loading) and your Data Plane URL. Network configuration, IT department
Incorrect SDK Version Ensure you are using a supported and up-to-date SDK version. Older versions might have compatibility issues or bugs. RudderStack SDK documentation, package manager (e.g., package.json for Node.js)
Event Volume Exceeded If you are on the free tier, confirm you haven't exceeded the 500,000 events/month limit. Events sent after this limit may be dropped. RudderStack dashboard > Usage

For persistent issues, RudderStack's official documentation provides extensive troubleshooting guides and a community forum for support.