@@ -6,6 +6,7 @@ description: Initialize the SDK in your browser extension's background and conte
66## Overview
77
88After configuring your manifest, you need to initialize the SDK in two places:
9+
9101 . ** Background Service Worker** : Manages offscreen documents and verification orchestration
10112 . ** 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
161166If 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
235240For 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+
2502561 . Check for syntax errors in background.js
2512572 . Verify ` "background" ` is correctly defined in manifest
2522583 . 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+
2592661 . Verify content script path matches your public directory
2602672 . Check ` run_at ` is set to ` "document_start" `
2612683 . 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
298279With background and content scripts set up, you're ready to implement verification flows in your extension popup or panel:
0 commit comments