Skip to content

Commit

Permalink
docs: add contribution guide for device mode integration
Browse files Browse the repository at this point in the history
  • Loading branch information
gitcommitshow authored Dec 19, 2024
1 parent 3cd77a1 commit 65f4cc0
Showing 1 changed file with 129 additions and 0 deletions.
129 changes: 129 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,135 @@ To contribute to this project, you may need to install RudderStack on your machi
For any questions, concerns, or queries, you can start by asking a question on our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community/) channel.
<br><br>

----
# Guide to develop your first device mode RudderStack integration

Before diving into RudderStack integration development, it's essential to understand the [RudderStack Event Specification](https://www.rudderstack.com/docs/event-spec/standard-events/). This specification serves as the foundation for collecting data in a consistent format and then transforming data for the target destinations. In this guide, we'll focus specifically on developing a destination integration in device mode integration type.

## Understanding integration types
RudderStack supports two primary integration modes:

1. **Cloud Mode Integration**: Events are routed through the RudderStack data plane in this mode
2. **Device Mode Integration**: Events are sent directly from the client to the destination in this mode

## Integration development journey

### 1. Initial setup and configuration
First, you'll need to configure the RudderStack UI in the [`rudder-integrations-config`](https://github.com/rudderlabs/rudder-integrations-config) repository:
- Navigate to [`src/configurations/destinations`](./src/configurations/destinations)
- Add necessary configuration files for dashboard setup
- Prepare integration documentation or planning documents

### 2. Core development steps

#### Setting up the development environment
```bash
# Clone the repository
git clone https://github.com/rudderlabs/rudder-sdk-js
# Setup the project
npm run setup
```

#### Essential components
Your integration will require several key files:

1. **Constants definition** (`/packages/analytics-js-common/src/constants/integrations`)
- Integration name
- Display name
- Directory name

2. **Main integration code** (`packages/analytics-js-integrations/src/integrations`)
```javascript
// index.js and browser.js structure
class TestIntegrationOne {
constructor(config, analytics, destinationInfo) {
// initialization code
}

init() {
// SDK initialization
}

// Core methods
isLoaded() { /**Your destination SDK is loaded successfully**/}
isReady() { /**At this point, you can start sending supported events to your destination e.g. track, identify, etc.**/ }

// Event handling
identify(rudderElement) {}
track(rudderElement) {}
page(rudderElement) {}
alias(rudderElement) {}
group(rudderElement) {}
}
```

### 3. Building and testing

#### Build process
```bash
# For legacy build
npm run build:integration --environment INTG_NAME:TestIntegrationOne

# For modern build
npm run build:integration:modern --environment INTG_NAME:TestIntegrationOne
```

#### Testing setup
1. Serve the bundle:
```bash
npx serve dist/cdn/js-integrations
```
2. Configure test environment:
- Modify `public/index.html` for mock source config
- Set environment variables (WRITE_KEY, DATAPLANE_URL)
- Run `npm run start`

### 4. Automated testing
Implement automated tests for your integration:
```bash
# Run tests for specific destination
npm run test:ts -- component --destination=my_destination
```

### 5. UI configuration
Two approaches for adding UI configurations:

1. **Manual configuration**
- Add config files in `src/configurations/destinations`
- Use existing templates as reference

2. **Automated generation**
```bash
python3 scripts/configGenerator.py <path-to-placeholder-file>
```

## Deployment and support
Once development is complete:
1. The RudderStack team will handle production deployment
2. An announcement will be made in the [Release Notes](https://www.rudderstack.com/docs/releases/) and Slack `#product-releases` channel
3. Ongoing support is available through:
- GitHub PR feedback
- [RudderStack Slack community](https://rudderstack.com/join-rudderstack-slack-community/) `#contributing-to-rudderstack` channel

## Best practices
- Draft the integration plan document before coding
- Be judicious in choosing where you want to allow integration users to configure settings (in the control plane vs the sdk instrumentation code)
- Follow existing integration examples
- Document all configuration options
- Keep code modular and maintainable

Building a RudderStack integration requires attention to detail and thorough testing. The RudderStack team provides support throughout the development process, ensuring your integration meets quality standards and works reliably in production.

## References

- [RudderStack community on Slack](https://rudderstack.com/join-rudderstack-slack-community/)
- [Recording of the community workshop to develop device mode integration](https://youtu.be/70w2ESMBPCI)
- [Guide to develop source and cloud mode destination integration](https://github.com/rudderlabs/rudder-transformer/blob/develop/CONTRIBUTING.md)
- [Recording of the community workshop to develop source and cloud mode integration](https://youtu.be/OD2vCYG-P7k)
- [RudderStack Event Specification](https://www.rudderstack.com/docs/event-spec/standard-events/)

----

### We look forward to your feedback on improving this project!

<!----variables---->
Expand Down

0 comments on commit 65f4cc0

Please sign in to comment.