Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add contribution guide for device mode integration #1979

Merged
merged 6 commits into from
Dec 26, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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) {}
}
```
gitcommitshow marked this conversation as resolved.
Show resolved Hide resolved

### 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

gitcommitshow marked this conversation as resolved.
Show resolved Hide resolved
## 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
Loading