dev.Carbonguru.io

CarbonGuru User Onboarding Guide


Welcome to CarbonGuru! 🌍

Get started with CarbonGuru in just a few steps. This guide will walk you through everything you need to know to start tracking the carbon footprint of your online shopping.

Quick Navigation

Step 1: Create Your CarbonGuru Account

Register for a Free Account

  1. Visit the Registration Page
  2. Enter Your Information
    • Username: Choose a unique username
    • Email: Enter your email address (you’ll receive a confirmation)
  3. Check Your Email
    • Look for an email from CarbonGuru with your temporary password
    • Check your spam folder if you don’t see it within a few minutes
  4. Log In for the First Time

✅ Checkpoint: You should now be logged into your CarbonGuru account!

Step 2: Install Firefox Developer Edition

Why Firefox Developer Edition? CarbonGuru’s browser extension is currently optimized for Firefox Developer Edition, which allows unsigned extensions for development and testing.

Download Firefox Developer Edition

  1. Visit the Official Download Page
  2. Download for Your Operating System
    • Windows: Click “Download Firefox Developer Edition” – save the installer
    • macOS: Click “Download Firefox Developer Edition” – save the .dmg file
    • Linux: Choose your distribution (most common is .tar.bz2)
  3. Install Firefox Developer Edition
    • Windows:
      1. Run the installer (.exe file)
      2. Follow the installation wizard
      3. Choose “Custom” installation if you want to specify location
      4. Click “Install” and wait for completion
    • macOS:
      1. Open the .dmg file
      2. Drag the Firefox Developer Edition icon to your Applications folder
      3. Open Applications and double-click Firefox Developer Edition
      4. If you see a security warning, go to System Preferences → Security & Privacy → click “Open Anyway”
    • Linux:
      1. Extract the downloaded .tar.bz2 file: tar -xjf firefox-*.tar.bz2
      2. Move to /opt: sudo mv firefox /opt/firefox-developer
      3. Create symlink: sudo ln -s /opt/firefox-developer/firefox /usr/local/bin/firefox-developer
      4. Launch: firefox-developer
  4. Launch Firefox Developer Edition
    • Open the browser – you should see the Firefox Developer Edition welcome screen

Enable Unverified Extensions (CRITICAL STEP)

⚠️ Important: This step is required for the CarbonGuru extension to work in Firefox Developer Edition.

  1. Open About:Config
    • Type about:config in the Firefox address bar and press Enter
    • Click “Accept the Risk and Continue” when warned
  2. Enable Unsigned Extensions
    • In the search box at the top, type: xpinstall.signatures.required
    • You should see one result with a toggle button
    • Click the toggle button to change the value from true to false
    • The row should now show: xpinstall.signatures.required = false
  3. Verify the Setting
    • The value should remain false (dark toggle on the left side)
    • You don’t need to restart Firefox for this to take effect

How to Disable Unverified Extensions (If Needed)

If you want to revert this setting later for security:

  1. Go back to about:config
  2. Search for xpinstall.signatures.required
  3. Click the toggle to change it back to true
  4. Note: The CarbonGuru extension will stop working if you do this

✅ Checkpoint: Firefox Developer Edition is installed and configured for unsigned extensions!

Step 3: Install the CarbonGuru Browser Extension

Method 1: Direct Installation (Recommended)

  1. Make Sure You’re Logged In
  2. Visit the Extension Download Page
  3. Approve the Installation
    • Firefox will show a popup asking “Add CarbonGuru?”
    • Click “Add”
    • You may see a warning about unverified add-ons – click “Continue to Installation”
  4. Confirm Installation
    • You should see “CarbonGuru has been added to Firefox”
    • The CarbonGuru icon should appear in your browser toolbar (top-right)

Method 2: Manual Installation from About:Debugging

If direct installation doesn’t work, use this method:

  1. Download the Extension File
    • Right-click this link and choose “Save Link As”: carbonguru-dev.xpi
    • Save it to your Downloads folder or Desktop
  2. Open Firefox Debugging Page
    • Type about:debugging#/runtime/this-firefox in the address bar and press Enter
  3. Load the Extension
    • Click the “Load Temporary Add-on…” button
    • Navigate to where you saved carbonguru-dev.xpi
    • Select the file and click “Open”
  4. Verify Installation
    • The extension should appear in the “Temporary Extensions” section
    • The CarbonGuru icon should appear in your toolbar

⚠️ Note: Temporary extensions are removed when you close Firefox. For permanent installation, use Method 1 or see the update instructions below.

✅ Checkpoint: The CarbonGuru extension is installed and visible in your browser!

Alternative: Install as Temporary Add-on

Use this method if you cannot or do not want to permanently enable unverified extensions in Firefox.

⚠️ Important Limitation: Temporary add-ons are automatically removed when you close Firefox. You’ll need to reinstall the extension each time you open Firefox.

When to Use This Method

  • You’re using regular Firefox (not Developer Edition) and can’t change settings
  • You don’t want to permanently disable signature verification for security reasons
  • You’re testing the extension and don’t need it permanently installed
  • You’re on a managed/corporate computer where you can’t change Firefox settings

Step-by-Step: Temporary Installation

Step 1: Download the Extension File

  1. Right-click this link and choose “Save Link As…”:
  2. Save to an easy-to-find location
    • Save to your Desktop or Downloads folder
    • Remember where you saved it – you’ll need to find it again later
    • Do NOT rename the file – keep it as carbonguru-dev.xpi
  3. Verify the download
    • The file should be around 1-2 MB in size
    • File name should end with .xpi

Step 2: Open Firefox Debugging Page

  1. Open a new tab in Firefox
  2. Type this exactly in the address bar:
    • about:debugging#/runtime/this-firefox
  3. Press Enter
    • You should see the Firefox Debugging page
    • The page title should say “This Firefox”

Step 3: Load the Temporary Add-on

  1. Find the “Temporary Extensions” section
    • Look for the heading “Temporary Extensions” on the page
    • Under it, you’ll see a button labeled “Load Temporary Add-on…”
  2. Click “Load Temporary Add-on…”
    • A file browser window will open
  3. Navigate to where you saved the extension
    • Go to your Desktop or Downloads folder (wherever you saved it)
    • Find the file named carbonguru-dev.xpi
  4. Select the file and click “Open”
    • Firefox will load the extension immediately
    • You should see “CarbonGuru” appear in the Temporary Extensions list

Step 4: Verify Installation

  1. Check the extension appears on the debugging page
    • You should see “CarbonGuru” with extension details
    • Shows: Name, version number, internal UUID
    • Status indicator should show it’s active
  2. Look for the CarbonGuru icon in your toolbar
    • The CarbonGuru icon should appear in the top-right toolbar
    • It may be in the extensions menu (puzzle piece icon)
  3. Test the extension
    • Click the CarbonGuru icon
    • The extension popup should open
    • You should see the CarbonGuru interface

Step 5: Pin the Extension (Optional but Recommended)

Make the icon always visible in your toolbar:

  1. Right-click the toolbar area (near other extension icons)
  2. Select “Customize Toolbar…”
  3. Find the CarbonGuru icon in the available items
  4. Drag it to your preferred position in the toolbar
  5. Click “Done”

✅ Success! The CarbonGuru extension is now installed and ready to use!

Important: What Happens When You Close Firefox

Temporary Extensions Are Removed

When you close Firefox (quit the application completely), the temporary add-on will be automatically removed. This is a Firefox security feature for unverified extensions.

How to Reinstall After Closing Firefox

Every time you open Firefox and want to use CarbonGuru, follow these quick steps:

  1. Open Firefox
  2. Go to about:debugging#/runtime/this-firefox
    • You can bookmark this page for quick access
  3. Click “Load Temporary Add-on…”
  4. Select carbonguru-dev.xpi from your Desktop/Downloads
  5. Click “Open”

⏱️ This takes about 15 seconds once you’re familiar with the process.

Tips for Easier Reinstallation

Tip 1: Bookmark the Debugging Page

  1. Visit about:debugging#/runtime/this-firefox
  2. Press Ctrl+D (or Cmd+D on Mac) to bookmark
  3. Name it: “Load CarbonGuru Extension”
  4. Save to your Bookmarks Bar for one-click access

Tip 2: Keep the .xpi File Easily Accessible

  • Keep carbonguru-dev.xpi on your Desktop (not buried in folders)
  • Or create a “CarbonGuru” folder on your Desktop and keep it there
  • Don’t delete or move the file after first installation

Tip 3: Create a Firefox Profile Just for CarbonGuru

Advanced users can create a dedicated Firefox profile with permanent settings:

  1. Type about:profiles in Firefox address bar
  2. Click “Create a New Profile”
  3. Name it “CarbonGuru” and create it
  4. Launch Firefox with this profile
  5. In this profile, enable unsigned extensions permanently (Step 2 from main guide)
  6. Switch to this profile when using CarbonGuru

Checking Temporary Extension Status

To see if the extension is currently loaded:

  1. Go to about:debugging#/runtime/this-firefox
  2. Look under “Temporary Extensions”
  3. If CarbonGuru is listed → Extension is active ✅
  4. If section is empty → Extension not loaded, reinstall it ❌

Comparing Installation Methods

Feature Permanent Installation
(Firefox Developer Edition)		 Temporary Add-on
(Any Firefox)
Stays after closing Firefox ✅ Yes ❌ No
Automatic updates ✅ Yes ❌ No (manual download)
One-time setup ✅ Yes ❌ Reinstall each time
Works in regular Firefox ❌ No (needs Dev Edition) ✅ Yes
Security setting change required ⚠️ Yes (about:config) ✅ No
Setup time ~10 minutes (once) ~15 seconds (each time)
Best for Regular CarbonGuru users Testing, occasional use, or restricted computers

Troubleshooting Temporary Add-on Installation

Problem: Can’t find “Load Temporary Add-on…” button

Solution:

  • Make sure you’re at about:debugging#/runtime/this-firefox (not just about:debugging)
  • Look under the “Temporary Extensions” heading, not “Extensions”
  • Scroll down if needed – the button might be below the fold

Problem: “This add-on could not be installed” error

Solution:

  • Make sure the file is named carbonguru-dev.xpi (with .xpi extension)
  • Re-download the file – it may have been corrupted
  • Check file size – should be 1-2 MB, not a few KB
  • Try downloading with a different browser and then loading in Firefox

Problem: Extension works but icon doesn’t appear in toolbar

Solution:

  1. Click the puzzle piece icon (Extensions menu) in the toolbar
  2. You should see CarbonGuru listed there
  3. Click the gear icon next to CarbonGuru
  4. Select “Pin to Toolbar”

Problem: Extension disappeared but Firefox is still open

Solution:

  • Go to about:debugging#/runtime/this-firefox
  • Check if the extension is still listed under “Temporary Extensions”
  • If not listed, Firefox may have restarted in the background
  • Reload the extension using the steps above

Updating the Temporary Add-on

When a new version of CarbonGuru is released:

  1. Download the new .xpi file
    • Visit: carbonguru-dev.xpi
    • Save it (it will overwrite the old version or save as a new file)
  2. Remove the old temporary extension (if loaded)
    • Go to about:debugging#/runtime/this-firefox
    • Find CarbonGuru under “Temporary Extensions”
    • Click “Remove”
  3. Load the new version
    • Click “Load Temporary Add-on…”
    • Select the newly downloaded .xpi file
    • The new version will load immediately
  4. Verify the new version
    • Click the CarbonGuru icon
    • Check the version number at the bottom of the popup
    • It should show the new version number

💡 Recommendation

If you plan to use CarbonGuru regularly (more than once a week), we strongly recommend installing Firefox Developer Edition and using the permanent installation method. This provides:

  • ✅ Automatic updates
  • ✅ No reinstallation needed
  • ✅ Better user experience
  • ✅ All features work reliably

Temporary add-ons are best for occasional use, testing, or situations where you cannot install Firefox Developer Edition.

✅ Checkpoint: You now know how to install and manage CarbonGuru as a temporary add-on!

Step 4: Update Your Extension

CarbonGuru offers two ways to keep your extension up to date:

Option A: Manual Update (User-Triggered)

When to use: When you see a notification about a new version, or want to ensure you have the latest features.

  1. Click the CarbonGuru Extension Icon
    • Find the CarbonGuru icon in your Firefox toolbar (usually top-right)
    • Click the icon to open the extension popup
  2. Check for Updates
    • Look for an “Update Available” notification in the popup
    • Or click the “Check for Updates” button (if visible)
  3. Install the Update
    • Click “Update Now” when prompted
    • The extension will download the latest version
    • Firefox will prompt you to approve the update
    • Click “Update” or “Allow”
  4. Reload the Extension
    • The extension may automatically reload
    • If not, close and reopen Firefox
    • Verify the new version number in the extension popup

Option B: Automatic Updates (Scheduled)

When it happens: CarbonGuru automatically checks for updates every 24 hours.

  1. How It Works
    • The extension checks updates.json daily
    • If a new version is available, Firefox downloads it automatically
    • You’ll see a notification: “CarbonGuru has been updated”
  2. Enable Auto-Updates (if disabled)
    • Type about:addons in the Firefox address bar
    • Find CarbonGuru in the list of extensions
    • Click the three-dot menu (⋯) next to CarbonGuru
    • Ensure “Allow automatic updates” is checked
  3. Check Your Version
    • Click the CarbonGuru icon in your toolbar
    • Look for the version number at the bottom of the popup
    • Example: “Version 1.7.8.1363”

Force an Update Check

If you want to check for updates immediately:

  1. Visit: about:addons
  2. Click the gear icon (⚙️) at the top
  3. Select “Check for Updates”
  4. Firefox will check all extensions including CarbonGuru

✅ Checkpoint: You know how to update your extension manually and automatically!

Step 5: Connect Your Gmail Account

Why connect Gmail? CarbonGuru can analyze your email receipts to automatically track carbon footprints from online purchases, even without visiting the shopping cart page.

Prerequisites

  • ✅ CarbonGuru account created and logged in
  • ✅ CarbonGuru extension installed in Firefox
  • ✅ A Gmail account you want to connect

Connect Gmail to CarbonGuru

  1. Open Gmail in Firefox
  2. Open the CarbonGuru Extension
    • Click the CarbonGuru icon in your Firefox toolbar
    • The extension popup will open
  3. Access Gmail & Email Settings
    • In the CarbonGuru popup, scroll down to the “Extension Admin” section
    • Click to expand the Extension Admin section if it’s collapsed
    • Look for the “📧 Gmail Settings →” link
    • Click the link to open the Gmail & Email Settings page in a new tab
  4. Authorize CarbonGuru
    • Click “Connect Gmail Account” or “Authorize”
    • A new window will open with Google’s OAuth consent screen
  5. Grant Permissions
    • Google will ask you to sign in (if not already signed in)
    • Review the permissions CarbonGuru is requesting:
      • Read your email messages: To find order receipts and shipping notifications
      • View metadata about your messages: To identify relevant emails without reading all content
    • Click “Allow” to grant these permissions
  6. Confirm Connection
    • You’ll be redirected back to CarbonGuru
    • You should see a success message: “Gmail connected successfully!”
    • Your Gmail address should appear in the extension popup

What Happens Next?

  • Automatic Email Scanning: CarbonGuru will periodically check your Gmail for order receipts
  • Carbon Tracking: When receipts are found, CarbonGuru extracts order information and calculates carbon footprints
  • Privacy: Only emails matching order/receipt patterns are processed. CarbonGuru does not read personal emails.

Alternative: Email Forwarding with Tokens

Want to forward receipts from other email accounts? You can use CarbonGuru’s email forwarding feature to send receipts from any email address.

How Email Forwarding Works

  1. Generate Your Email Token
    • On the Gmail & Email Settings page, find the “Email Forwarding” section
    • Click “Generate Token” to create your unique forwarding token (format: CG-XXXXXXXX)
    • Your token will appear immediately – save it for the next step
  2. Set Up Email Forwarding
    • In your other email account (Outlook, Yahoo, etc.), set up an auto-forward rule
    • Forward emails to: email_processing@carbonguru.io
    • In the subject line or body, include your token: CG-XXXXXXXX
  3. Receipts Get Processed Automatically
    • Any forwarded email with your token will be processed by CarbonGuru
    • Order information will be extracted and carbon footprints calculated
    • Results appear in your Product Footprints

💡 Tip: You can regenerate your token at any time if you think it’s been compromised. Visit the Gmail & Email Settings page and click “Regenerate Token”.

Manage Gmail & Email Settings

View Connected Account

  1. Visit the Gmail & Email Settings page
  2. Or click the “📧 Gmail Settings →” link in the Extension Admin section of the popup
  3. You’ll see your connected Gmail address and OAuth status
  4. Your email forwarding token (if generated) will also be displayed

Disconnect Gmail (If Needed)

  1. Visit the Gmail & Email Settings page
  2. Find the “Gmail OAuth Connection” section
  3. Click “Disconnect” or “Remove Account”
  4. Confirm the disconnection when prompted
  5. To fully revoke access:

Reconnect Gmail

If you disconnected and want to reconnect:

  1. Visit the Gmail & Email Settings page
  2. Follow the connection steps above
  3. You may need to re-authorize the permissions

Manage Email Forwarding Token

  1. Visit the Gmail & Email Settings page
  2. Find the “Email Forwarding” section
  3. Generate Token: Click “Generate Token” if you don’t have one yet
  4. Regenerate Token: Click “Regenerate Token” to create a new token (old token will stop working)
  5. Copy your token and use it in your email forwarding rules

✅ Checkpoint: Your Gmail is connected and CarbonGuru can now track receipts automatically!

Troubleshooting Common Issues

Extension Installation Problems

Problem: “This add-on could not be installed because it has not been verified”

Solution:

  1. Make sure you’re using Firefox Developer Edition (not regular Firefox)
  2. Check that xpinstall.signatures.required is set to false in about:config
  3. Restart Firefox and try again

Problem: Extension icon doesn’t appear in toolbar

Solution:

  1. Go to about:addons
  2. Verify CarbonGuru is in the list and enabled
  3. Right-click the toolbar and select “Customize Toolbar”
  4. Look for the CarbonGuru icon and drag it to your toolbar

Problem: Extension disappears after closing Firefox

Solution:

  • You installed as a “temporary extension” from about:debugging
  • Use Method 1 (Direct Installation) from Step 3 for permanent installation
  • Or reinstall using the .xpi file link each time you open Firefox

Account and Login Issues

Problem: Forgot password

Solution:

  1. Visit: https://dev.carbonguru.io/wp-login.php?action=lostpassword
  2. Enter your username or email
  3. Check your email for a password reset link
  4. Click the link and create a new password

Problem: Didn’t receive confirmation email

Solution:

  1. Check your spam/junk folder
  2. Wait 10-15 minutes (emails can be delayed)
  3. Try registering again – you may have made a typo in your email address
  4. Contact support if still not receiving emails

Gmail Connection Issues

Problem: “Authorization failed” when connecting Gmail

Solution:

  1. Make sure you’re logged into CarbonGuru first
  2. Check that pop-ups are not blocked in Firefox
  3. Try using an incognito/private window
  4. Clear your browser cache and cookies, then try again

Problem: Gmail shows as connected but not scanning emails

Solution:

  1. Disconnect and reconnect your Gmail account
  2. Verify permissions at Google Account Permissions
  3. Ensure CarbonGuru has “Read” access to Gmail
  4. Wait 24 hours – initial scanning can take time for large inboxes

Extension Update Issues

Problem: Updates not installing automatically

Solution:

  1. Go to about:addons
  2. Click the three-dot menu (⋯) next to CarbonGuru
  3. Ensure “Allow automatic updates” is checked
  4. Manually trigger an update check (gear icon → Check for Updates)

Problem: Update check says “no updates available” but I know there’s a new version

Solution:

  1. Check the version number at updates.json
  2. Clear Firefox cache: Settings → Privacy & Security → Clear Data
  3. Restart Firefox and check for updates again
  4. As a last resort, uninstall and reinstall the extension

Firefox Developer Edition Issues

Problem: Can’t find xpinstall.signatures.required in about:config

Solution:

  1. Make sure you’re in Firefox Developer Edition, not regular Firefox
  2. Type the preference name exactly: xpinstall.signatures.required
  3. If it still doesn’t appear, it may have been removed in newer versions – check Firefox version

Problem: Firefox won’t let me install Developer Edition alongside regular Firefox

Solution:

  • Windows/Linux: You can install both. Just choose different installation directories
  • macOS: Rename one of them (e.g., “Firefox Developer Edition.app”) before installing the other
  • Both versions can coexist and run simultaneously

Need More Help?

Resources

Contact Support

If you’re still having trouble after trying the troubleshooting steps:

  • Email: support@carbonguru.io (include your username and a description of the issue)
  • Include:
    • Your CarbonGuru username
    • Firefox version (Help → About Firefox)
    • Extension version (visible in extension popup)
    • Operating system and version
    • Description of the problem and what you’ve tried

You’re All Set! 🎉

Congratulations! You’ve successfully:

  • ✅ Created your CarbonGuru account
  • ✅ Installed Firefox Developer Edition with proper settings
  • ✅ Installed the CarbonGuru browser extension
  • ✅ Learned how to keep your extension updated
  • ✅ Connected your Gmail for automatic receipt tracking

What’s Next?

  • Start shopping online and watch CarbonGuru track your carbon footprint automatically
  • Visit your Product Footprints page to see your impact
  • Explore ways to reduce your carbon footprint with alternative products

Happy carbon tracking! 🌱