Skip to content

Commit aaaa4c0

Browse files
riderxriderx
authored
docs: add RudderStack plugin website pages (#545)
* docs: add RudderStack plugin website pages * docs: address RudderStack PR feedback
1 parent c6401e5 commit aaaa4c0

File tree

7 files changed

+300
-0
lines changed

7 files changed

+300
-0
lines changed

‎astro.config.mjs‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,11 @@ export default defineConfig({
333333
description: 'Google Tag Manager integration plugin',
334334
paths: ['docs/plugins/gtm/**'],
335335
},
336+
{
337+
label: 'Plugin RudderStack',
338+
description: 'RudderStack analytics and identity tracking plugin',
339+
paths: ['docs/plugins/rudderstack/**'],
340+
},
336341
{
337342
label: 'Plugin Health',
338343
description: 'health data access plugin for HealthKit and Google Fit',
@@ -1044,6 +1049,14 @@ export default defineConfig({
10441049
],
10451050
collapsed: true,
10461051
},
1052+
{
1053+
label: 'RudderStack',
1054+
items: [
1055+
{ label: 'Overview', link: '/docs/plugins/rudderstack/' },
1056+
{ label: 'Getting started', link: '/docs/plugins/rudderstack/getting-started' },
1057+
],
1058+
collapsed: true,
1059+
},
10471060
{
10481061
label: 'Health',
10491062
items: [

‎public/icons/plugins/rudderstack.svg‎

Lines changed: 31 additions & 0 deletions
Loading

‎src/config/plugins.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,14 @@ export const actions = [
348348
title: 'GTM',
349349
icon: 'ChartBar',
350350
},
351+
{
352+
name: '@capgo/capacitor-rudderstack',
353+
author: 'github.com/Cap-go',
354+
description: 'RudderStack analytics, identity resolution, screen tracking, and delivery controls for Capacitor',
355+
href: 'https://github.com/Cap-go/capacitor-rudderstack/',
356+
title: 'RudderStack',
357+
icon: 'ChartBar',
358+
},
351359
{
352360
name: '@capgo/capacitor-health',
353361
author: 'github.com/Cap-go',

‎src/content/docs/docs/plugins/index.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,11 @@ The Updater plugin is the foundation of Capgo Cloud, enabling you to:
263263
description="Google Tag Manager integration for analytics and tracking."
264264
href="/docs/plugins/gtm/"
265265
/>
266+
<LinkCard
267+
title="RudderStack"
268+
description="Track events, identify users, send screen views, and forward identity data with a Cordova-compatible RudderStack API."
269+
href="/docs/plugins/rudderstack/"
270+
/>
266271
<LinkCard
267272
title="AppInsights"
268273
description="Application insights and analytics using the Apptopia AppInsights SDK."

‎src/content/docs/docs/plugins/rudderstack/getting-started.mdx‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: Getting Started
3+
description: Learn how to install and initialize @capgo/capacitor-rudderstack in your Capacitor app.
4+
sidebar:
5+
order: 2
6+
---
7+
8+
import { Steps } from '@astrojs/starlight/components';
9+
import { PackageManagers } from 'starlight-package-managers'
10+
11+
<Steps>
12+
1. **Install the package**
13+
<PackageManagers pkg="@capgo/capacitor-rudderstack" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
14+
15+
2. **Sync native projects**
16+
<PackageManagers type="exec" pkg="cap" args="sync" pkgManagers={['npm', 'pnpm', 'yarn', 'bun']} />
17+
18+
3. **Collect your RudderStack credentials**
19+
You need your RudderStack `writeKey` and, in most setups, your `dataPlaneUrl`.
20+
</Steps>
21+
22+
## Initialize RudderStack
23+
24+
Initialize the SDK as early as practical in your app startup:
25+
26+
```ts
27+
import { RudderStack } from '@capgo/capacitor-rudderstack';
28+
29+
await RudderStack.initialize('YOUR_WRITE_KEY', {
30+
dataPlaneUrl: 'https://your-dataplane.rudderstack.com',
31+
trackLifecycleEvents: true,
32+
recordScreenViews: false,
33+
logLevel: RudderStack.LogLevel.INFO,
34+
});
35+
```
36+
37+
The plugin keeps the Cordova-style signature, so existing Rudder Cordova integrations can usually migrate with minimal JavaScript changes.
38+
39+
## Identify users and track events
40+
41+
```ts
42+
await RudderStack.identify('user_123', {
43+
email: 'user@example.com',
44+
plan: 'pro',
45+
});
46+
47+
await RudderStack.track('Checkout Started', {
48+
value: 49,
49+
currency: 'EUR',
50+
});
51+
52+
await RudderStack.screen('Checkout', {
53+
step: 'shipping',
54+
});
55+
```
56+
57+
You can also use `group()` and `alias()` when your data model depends on account-level grouping or identity transitions.
58+
59+
## Per-call options
60+
61+
RudderStack supports external identifiers and destination-specific toggles:
62+
63+
```ts
64+
await RudderStack.track(
65+
'Purchase Completed',
66+
{
67+
orderId: 'ord_123',
68+
total: 99,
69+
},
70+
{
71+
externalIds: {
72+
brazeExternalId: 'user_123',
73+
},
74+
integrations: {
75+
All: true,
76+
Amplitude: false,
77+
},
78+
},
79+
);
80+
```
81+
82+
## Delivery and privacy controls
83+
84+
Useful operational methods:
85+
86+
```ts
87+
await RudderStack.putDeviceToken('PUSH_TOKEN');
88+
await RudderStack.putAdvertisingId('ADVERTISING_ID');
89+
await RudderStack.putAnonymousId('ANON_ID');
90+
await RudderStack.flush();
91+
await RudderStack.optOut(false);
92+
```
93+
94+
Use `reset()` when the active user signs out and you want to clear the current Rudder identity state.
95+
96+
## Platform notes
97+
98+
### iOS and Android
99+
100+
- The plugin wraps the native RudderStack SDKs directly, so there is no extra bridge dependency to install.
101+
- `trackLifecycleEvents`, `recordScreenViews`, `flushQueueSize`, `dbCountThreshold`, and related Rudder config values are supported from JavaScript.
102+
103+
### Web
104+
105+
- The web implementation is a compatibility shim for development and API parity.
106+
- It validates initialization state, but it does not send live events to RudderStack.
107+
108+
### Current Capacitor port limits
109+
110+
- `config.factories` from `rudder-sdk-cordova` is currently ignored.
111+
- Native destination factory companion plugins are not part of this first Capacitor release.
112+
113+
## Best practices
114+
115+
1. Initialize RudderStack once during app startup and keep the `writeKey` plus `dataPlaneUrl` in centralized runtime config.
116+
2. Call `identify()` after authentication and `reset()` on logout to keep profile transitions consistent.
117+
3. Gate `optOut()` and advertising-related identifiers behind your consent flow.
118+
4. Use `flush()` for critical handoff points if you need to reduce delivery latency before app backgrounding.
119+
120+
For the full API surface and native packaging details, see the [plugin repository](https://github.com/Cap-go/capacitor-rudderstack/).

‎src/content/docs/docs/plugins/rudderstack/index.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "@capgo/capacitor-rudderstack"
3+
description: Add RudderStack analytics, identity, screen tracking, and event delivery controls to your Capacitor app with native iOS and Android SDK support.
4+
tableOfContents: false
5+
next: false
6+
prev: false
7+
sidebar:
8+
order: 1
9+
label: "Introduction"
10+
hero:
11+
tagline: Use a Cordova-compatible RudderStack API in Capacitor to initialize, identify, group, track, screen, alias, and manage delivery control flows.
12+
image:
13+
file: ~public/icons/plugins/rudderstack.svg
14+
actions:
15+
- text: Get started
16+
link: /docs/plugins/rudderstack/getting-started/
17+
icon: right-arrow
18+
variant: primary
19+
- text: GitHub
20+
link: https://github.com/Cap-go/capacitor-rudderstack/
21+
icon: external
22+
variant: minimal
23+
---
24+
25+
import { Card, CardGrid } from '@astrojs/starlight/components';
26+
27+
<CardGrid stagger>
28+
<Card title="Cordova Migration" icon="rocket">
29+
Keep the familiar Rudder Cordova calling style while moving the implementation to a Capacitor-native bridge.
30+
</Card>
31+
<Card title="Native SDKs" icon="star">
32+
Uses the RudderStack Android and iOS SDKs directly, packaged for Capacitor 8 on both platforms.
33+
</Card>
34+
<Card title="Identity APIs" icon="shield-check">
35+
Send `identify`, `group`, and `alias` calls with traits, external IDs, and destination integration flags.
36+
</Card>
37+
<Card title="Event Tracking" icon="document">
38+
Track events and screen views from JavaScript with the same SDK instance used by the native bridge.
39+
</Card>
40+
<Card title="Delivery Controls" icon="setting">
41+
Flush queued events, opt users out, forward push tokens, and set advertising or anonymous identifiers when needed.
42+
</Card>
43+
<Card title="Documentation" icon="open-book">
44+
Follow the [Getting started guide](/docs/plugins/rudderstack/getting-started/) for installation, initialization, and common tracking patterns.
45+
</Card>
46+
</CardGrid>

‎src/content/plugins-tutorials/en/capacitor-rudderstack.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
locale: en
3+
---
4+
5+
# Using @capgo/capacitor-rudderstack
6+
7+
The `@capgo/capacitor-rudderstack` package brings RudderStack analytics, identity management, screen tracking, and delivery controls to Capacitor apps with native iOS and Android SDK support. Its main value is preserving the familiar Rudder Cordova call shape while moving the implementation to a Capacitor-native bridge.
8+
9+
## Installation
10+
11+
Install the plugin and sync native projects:
12+
13+
```bash
14+
bun add @capgo/capacitor-rudderstack
15+
bunx cap sync
16+
```
17+
18+
## Migration checklist
19+
20+
When moving from `rudder-sdk-cordova`, keep the migration simple:
21+
22+
1. Replace the Cordova import with `RudderStack` from `@capgo/capacitor-rudderstack`.
23+
2. Initialize once during app startup with your `writeKey` and `dataPlaneUrl`.
24+
3. Keep your existing `identify`, `group`, `track`, `screen`, and `alias` call order where possible.
25+
4. Wire consent and sign-out flows to `optOut()` and `reset()`.
26+
5. Use `flush()` for critical transitions when you want events delivered faster before backgrounding.
27+
28+
## Example application flow
29+
30+
The following pattern works well for most apps:
31+
32+
```ts
33+
import { RudderStack } from '@capgo/capacitor-rudderstack';
34+
35+
const rudderConfig = {
36+
writeKey: 'YOUR_WRITE_KEY',
37+
dataPlaneUrl: 'https://your-dataplane.rudderstack.com',
38+
};
39+
40+
await RudderStack.initialize(rudderConfig.writeKey, {
41+
dataPlaneUrl: rudderConfig.dataPlaneUrl,
42+
trackLifecycleEvents: true,
43+
});
44+
45+
await RudderStack.identify('user_123', {
46+
plan: 'pro',
47+
source: 'mobile-app',
48+
});
49+
50+
await RudderStack.track('Subscription Viewed', {
51+
placement: 'paywall',
52+
experiment: 'spring-pricing',
53+
});
54+
```
55+
56+
Keep destination routing or external IDs on the individual calls that need them instead of trying to centralize every integration rule at initialization time.
57+
58+
## Platform behavior
59+
60+
### Native apps
61+
62+
- The plugin packages native RudderStack SDK support for both iOS and Android.
63+
- Common config values such as `trackLifecycleEvents`, `recordScreenViews`, `flushQueueSize`, and `logLevel` are set from JavaScript.
64+
65+
### Web builds
66+
67+
- The web target is a compatibility shim for development.
68+
- It preserves the API shape but does not send live analytics events.
69+
70+
### Current limitation
71+
72+
- `config.factories` from the Cordova plugin is intentionally ignored in this first Capacitor release.
73+
74+
## Next steps
75+
76+
- Read the full [Getting started guide](https://capgo.app/docs/plugins/rudderstack/getting-started/).
77+
- Browse the plugin source and native packaging details on [github.com/Cap-go/capacitor-rudderstack](https://github.com/Cap-go/capacitor-rudderstack).

0 commit comments

Comments
 (0)