Skip to content

Commit 269a024

Browse files
committed
new updated docs with example
1 parent 3fb5bd2 commit 269a024

File tree

4 files changed

+1194
-481
lines changed

4 files changed

+1194
-481
lines changed

content/docs/browser-extension/extension-integration/setup.mdx

Lines changed: 33 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ description: Initialize the SDK in your browser extension's background and conte
66
## Overview
77

88
After configuring your manifest, you need to initialize the SDK in two places:
9+
910
1. **Background Service Worker**: Manages offscreen documents and verification orchestration
1011
2. **Content Script Loading**: Bridges communication (optional if using static manifest registration)
1112

@@ -27,7 +28,8 @@ console.log("Reclaim SDK initialized in background");
2728
```
2829

2930
<Callout type="info">
30-
**Idempotent Operation**: `initializeBackground()` is safe to call multiple times. The SDK handles duplicate initialization attempts gracefully, making it perfect for service worker reactivation scenarios.
31+
**Idempotent Operation**: `initializeBackground()` is safe to call multiple times. The SDK handles duplicate initialization attempts
32+
gracefully, making it perfect for service worker reactivation scenarios.
3133
</Callout>
3234

3335
### What Does Background Initialization Do?
@@ -60,6 +62,7 @@ Your `manifest.json` includes:
6062
```
6163

6264
**Advantages**:
65+
6366
- ✅ Automatic injection on all pages
6467
- ✅ No additional code required
6568
- ✅ Simpler to maintain
@@ -77,7 +80,7 @@ Add to your `manifest.json`:
7780
"permissions": [
7881
"offscreen",
7982
"cookies",
80-
"scripting" // Required for dynamic registration
83+
"scripting"
8184
]
8285
```
8386

@@ -93,21 +96,24 @@ chrome.runtime.onInstalled.addListener(() => {
9396
reclaimExtensionSDK.initializeBackground();
9497

9598
// Register content script dynamically
96-
chrome.scripting.registerContentScripts([
97-
{
98-
id: "reclaim-sdk-bridge",
99-
matches: ["<all_urls>"],
100-
js: ["reclaim-browser-extension-sdk/content/content.bundle.js"],
101-
runAt: "document_start",
102-
world: "ISOLATED"
103-
}
104-
], () => {
105-
if (chrome.runtime.lastError) {
106-
console.error("❌ Failed to register content script:", chrome.runtime.lastError);
107-
} else {
108-
console.log("✅ Reclaim SDK content script registered");
99+
chrome.scripting.registerContentScripts(
100+
[
101+
{
102+
id: "reclaim-sdk-bridge",
103+
matches: ["<all_urls>"],
104+
js: ["reclaim-browser-extension-sdk/content/content.bundle.js"],
105+
runAt: "document_start",
106+
world: "ISOLATED",
107+
},
108+
],
109+
() => {
110+
if (chrome.runtime.lastError) {
111+
console.error("❌ Failed to register content script:", chrome.runtime.lastError);
112+
} else {
113+
console.log("✅ Reclaim SDK content script registered");
114+
}
109115
}
110-
});
116+
);
111117
});
112118
```
113119

@@ -122,7 +128,7 @@ async function ensureContentScriptRegistered() {
122128
try {
123129
// Check if already registered
124130
const scripts = await chrome.scripting.getRegisteredContentScripts();
125-
const isRegistered = scripts.some(script => script.id === "reclaim-sdk-bridge");
131+
const isRegistered = scripts.some((script) => script.id === "reclaim-sdk-bridge");
126132

127133
if (!isRegistered) {
128134
await chrome.scripting.registerContentScripts([
@@ -131,8 +137,8 @@ async function ensureContentScriptRegistered() {
131137
matches: ["<all_urls>"],
132138
js: ["reclaim-browser-extension-sdk/content/content.bundle.js"],
133139
runAt: "document_start",
134-
world: "ISOLATED"
135-
}
140+
world: "ISOLATED",
141+
},
136142
]);
137143
console.log("✅ Reclaim SDK content script registered");
138144
} else {
@@ -155,7 +161,6 @@ chrome.runtime.onInstalled.addListener(() => {
155161
});
156162
```
157163

158-
159164
## Loading Multiple Content Scripts
160165

161166
If your extension has its own content scripts, load them after the SDK bridge:
@@ -189,8 +194,8 @@ chrome.runtime.onInstalled.addListener(async () => {
189194
matches: ["<all_urls>"],
190195
js: ["reclaim-browser-extension-sdk/content/content.bundle.js"],
191196
runAt: "document_start",
192-
world: "ISOLATED"
193-
}
197+
world: "ISOLATED",
198+
},
194199
]);
195200

196201
// Then register your content scripts
@@ -200,8 +205,8 @@ chrome.runtime.onInstalled.addListener(async () => {
200205
matches: ["<all_urls>"],
201206
js: ["your-content-script.js"],
202207
runAt: "document_end",
203-
world: "ISOLATED"
204-
}
208+
world: "ISOLATED",
209+
},
205210
]);
206211
});
207212
```
@@ -227,15 +232,15 @@ chrome.runtime.onInstalled.addListener(async () => {
227232

228233
```javascript
229234
// In the console, check if the SDK loaded:
230-
console.log("Reclaim SDK Content Script:", typeof window.__RECLAIM_SDK__ !== 'undefined');
235+
console.log("Reclaim SDK Content Script:", typeof window.__RECLAIM_SDK__ !== "undefined");
231236
```
232237

233238
### Check Registered Scripts
234239

235240
For dynamic registration, verify scripts are registered:
236241

237242
```javascript
238-
chrome.scripting.getRegisteredContentScripts().then(scripts => {
243+
chrome.scripting.getRegisteredContentScripts().then((scripts) => {
239244
console.log("Registered scripts:", scripts);
240245
});
241246
```
@@ -247,6 +252,7 @@ chrome.scripting.getRegisteredContentScripts().then(scripts => {
247252
**Symptoms**: Background initialization not running
248253

249254
**Solutions**:
255+
250256
1. Check for syntax errors in background.js
251257
2. Verify `"background"` is correctly defined in manifest
252258
3. Look for errors in the service worker console
@@ -256,6 +262,7 @@ chrome.scripting.getRegisteredContentScripts().then(scripts => {
256262
**Symptoms**: Verification fails, no communication with pages
257263

258264
**Solutions**:
265+
259266
1. Verify content script path matches your public directory
260267
2. Check `run_at` is set to `"document_start"`
261268
3. Ensure `host_permissions` includes target domains
@@ -267,32 +274,6 @@ chrome.scripting.getRegisteredContentScripts().then(scripts => {
267274

268275
**Solution**: This is usually harmless due to service worker reactivation. The SDK handles duplicate calls safely.
269276

270-
## Environment Variables (Optional)
271-
272-
For cleaner code, use environment variables for configuration:
273-
274-
```javascript
275-
// background.js
276-
const SDK_CONFIG = {
277-
debug: process.env.NODE_ENV === 'development',
278-
logLevel: process.env.SDK_LOG_LEVEL || 'info'
279-
};
280-
281-
reclaimExtensionSDK.initializeBackground(SDK_CONFIG);
282-
```
283-
284-
Configure in your build tool (Vite example):
285-
286-
```javascript
287-
// vite.config.js
288-
export default {
289-
define: {
290-
'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
291-
'process.env.SDK_LOG_LEVEL': JSON.stringify(process.env.SDK_LOG_LEVEL)
292-
}
293-
}
294-
```
295-
296277
## Next Steps
297278

298279
With background and content scripts set up, you're ready to implement verification flows in your extension popup or panel:

0 commit comments

Comments
 (0)