diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7bb52d9b..d013a8040 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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.

+---- +# 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 + ``` + +## 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!