Chrome Extension Publishing Guide — Publishing Guide

Chrome Web Store Publishing Guide

Complete guide from zero to published extension. Covers developer registration, store listing preparation, review process, updates, analytics, and monetization.

Table of Contents

1. Developer Account Registration
2. Preparing Your Extension for Submission
3. Screenshot and Promotional Image Requirements
4. Writing the Store Listing
5. Privacy Policy Requirements
6. Data Use Disclosure
7. Review Process
8. Responding to Reviewer Feedback
9. Update Workflow
10. Managing Multiple Versions
11. Analytics Dashboard and User Metrics
12. Handling User Reviews and Support
13. Monetization Options
14. Transferring Extension Ownership

Developer Account Registration

Before you can publish anything, you need a Chrome Web Store developer account.

Requirements

• A Google account (personal or Google Workspace)
• A one-time registration fee of $5 USD
• A verified email address

Registration Steps

1. Go to the Chrome Web Store Developer Dashboard
2. Sign in with your Google account
3. Accept the developer agreement
4. Pay the $5 registration fee via Google Payments
5. Complete identity verification (required since 2023)

Identity Verification

Google now requires identity verification for all new developer accounts:

• Individual developers: Provide government-issued photo ID and a selfie for identity matching
• Business/organization: Provide business registration documents, your role verification, and a D-U-N-S number or equivalent

Verification typically takes 1-3 business days. You cannot upload extensions until verification is complete.

Account Limits

• New accounts are limited to publishing 20 extensions
• Accounts with a good track record can request limit increases
• Google Workspace administrators can manage developer accounts for their organization, which allows publishing under the company’s name

Preparing Your Extension for Submission

Before uploading, make sure your extension is ready.

Manifest Requirements

Your manifest.json must include:

{
  "manifest_version": 3,              // MV2 no longer accepted for new submissions
  "name": "My Extension",             // 75 characters max
  "version": "1.0.0",                 // Semver recommended
  "description": "Brief description", // 132 characters max
  "icons": {
    "16": "icons/icon-16.png",
    "32": "icons/icon-32.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  }
}

Icon Requirements

All icons must be PNG format with no transparency issues. The 128x128 icon is the most visible – invest in making it look professional.

Building the ZIP Package

The Chrome Web Store accepts a .zip file containing your extension files. Do not include:

• Source maps (.map files)
• Test files and test configuration
• node_modules/
• .git/ directory
• Development configuration files (.env, tsconfig.json, etc.)
• Documentation and README files

A typical build script:

#!/bin/bash
# build-zip.sh
VERSION=$(node -p "require('./package.json').version")
FILENAME="extension-v${VERSION}.zip"

# Build the extension
npm run build

# Create the zip from the dist directory
cd dist
zip -r "../${FILENAME}" . -x "*.map"
cd ..

echo "Created ${FILENAME}"

Pre-Submission Checklist

• Extension works in Chrome stable (not just Canary/Dev)
• All declared permissions are actually used
• No console.log statements left in production code
• Service worker handles errors gracefully
• Content scripts do not break popular websites
• The extension’s name does not infringe on trademarks
• Version number has been incremented from any previous submission

Screenshot and Promotional Image Requirements

Visual assets are critical for conversion. Users decide whether to install based on screenshots before reading the description.

Screenshots

Tips for effective screenshots:

• Show the extension actually doing something useful
• Add brief text annotations highlighting key features
• Use a clean, consistent visual style across all screenshots
• First screenshot is the most important – it appears in search results
• Do not include the Chrome browser frame (just the content area)
• Avoid text-heavy screenshots that are unreadable at small sizes

Promotional Images

The marquee tile is only used if Chrome editors choose to feature your extension. Include it anyway – you never know when they might pick yours.

Store Icon

Your 128x128 icon from the manifest is used as the store listing icon. It should be:

• Recognisable at small sizes
• Distinct from other extensions in your category
• Not a photograph or overly detailed image
• Consistent with your extension’s branding

Writing the Store Listing

The store listing is your sales page. Every field matters.

Name (Maximum 75 Characters)

• Be descriptive but concise
• Include a primary keyword (e.g., “Tab Manager” not “Tabify”)
• Do not include “Chrome” or “Extension” in the name (it is implied)
• Do not use ALL CAPS
• Avoid special characters and emoji

Short Description (Maximum 132 Characters)

This appears in search results. Make every character count:

Good: "Block distracting websites during work hours with customizable schedules"
Bad:  "A really cool and awesome extension that helps you be more productive!!!"

Detailed Description (Maximum 16,384 Characters)

Structure it for scanning:

[Opening hook -- what problem does this solve?]

FEATURES:
- Feature 1: brief explanation
- Feature 2: brief explanation
- Feature 3: brief explanation

HOW IT WORKS:
1. Step one
2. Step two
3. Step three

PERMISSIONS:
This extension requests [permission] to [reason].

PRIVACY:
[Brief privacy statement with link to full policy]

SUPPORT:
[How to get help -- email, GitHub issues, etc.]

Category Selection

Choose the most specific category that applies:

Picking the wrong category can lead to rejection or poor discoverability.

Language and Localisation

• Set a primary language for your listing
• Provide localised descriptions for target markets
• Use _locales/ in your extension for UI strings
• The store supports 55+ languages for listings

Privacy Policy Requirements

A privacy policy is required if your extension collects or transmits any user data.

When a Privacy Policy is Required

You must provide a privacy policy URL if your extension:

• Handles personally identifiable information (PII)
• Uses host permissions (accesses website content)
• Requests the identity or identity.email permission
• Uses remote code or connects to external servers
• Uses analytics or tracking
• Collects any form of user data, even anonymised

In practice, almost every extension needs a privacy policy. If your extension only uses storage for local preferences and has no host permissions, you might be exempt – but providing one anyway is safer.

What the Privacy Policy Must Include

• What data you collect
• How you collect it
• Why you collect it (purpose)
• How you store and protect it
• Who you share it with (if anyone)
• How users can request data deletion
• How you notify users of policy changes
• Your contact information

Hosting Your Privacy Policy

Options for hosting:

• A page on your website
• A GitHub Pages site
• A Google Doc set to “anyone with the link can view”
• A dedicated privacy policy hosting service

The URL must be publicly accessible. Do not link to a page that requires login.

Data Use Disclosure

The Chrome Web Store requires a detailed data use disclosure that explains every type of data your extension handles. This appears on your listing page and is reviewed carefully.

Data Types

You must declare which of these data types you collect:

Justifying Permissions in the Disclosure

For each permission that accesses user data, explain the purpose:

Certification

You must certify that your extension:

1. Does not sell user data to third parties
2. Does not use or transfer data for purposes unrelated to the extension’s core functionality
3. Does not use or transfer data to determine creditworthiness or for lending
4. Complies with Chrome Web Store policies

False certifications will result in removal of your extension and potential account suspension.

Review Process

Every submission goes through a review by Google’s team (automated and manual).

Timeline

Review times can spike during holidays or after policy changes. Plan your releases accordingly.

What Reviewers Check

1. Policy compliance: Does the extension follow Chrome Web Store policies?
2. Permission justification: Does each permission have a legitimate use?
3. Functionality: Does the extension do what its description claims?
4. Malware/abuse: Does it contain malicious code or deceptive behaviour?
5. Privacy: Is the data use disclosure accurate?
6. Quality: Does it meet minimum quality standards?

Common Rejection Reasons

Remote Code Restrictions (MV3)

Manifest V3 strictly prohibits executing remotely hosted code. All JavaScript must be bundled in the extension package. You can still:

• Fetch data (JSON, configuration) from remote servers
• Use chrome.scripting.executeScript() with code that is in the package
• Load remote CSS (with some restrictions)
• Connect to WebSocket servers for real-time data

You cannot:

• Use eval() or new Function() with remote strings
• Inject <script> tags pointing to CDNs
• Use chrome.scripting.executeScript({ code: remoteString })

Responding to Reviewer Feedback

If your extension is rejected, you will receive an email with the reason.

How to Respond

1. Read the rejection email carefully. Identify the specific policy or requirement that was violated.

2. Fix the issue completely. Do not submit a partial fix hoping it will pass – it will not.

3. Update the version number. Even if the only change is a fix for the rejection, increment the version.

4. Re-submit with a note. Use the “Additional notes for reviewer” field to explain what you changed and why.

5. Be patient. Re-reviews often take longer than initial reviews.

Appealing a Rejection

If you believe the rejection was incorrect:

1. Reply to the rejection email with a clear, factual explanation
2. Reference specific Chrome Web Store policies
3. Provide evidence (screenshots, code snippets) showing compliance
4. Remain professional – combative responses rarely help

Appeals are reviewed by a different team member. Response time is typically 5-10 business days.

Common Mistakes in Re-Submissions

• Submitting without actually fixing the issue
• Changing the extension name to evade a trademark rejection
• Adding a permission that was previously flagged as unnecessary
• Not updating the privacy policy when data handling changes
• Submitting the same package with only a version bump

Update Workflow

Publishing updates follows a similar flow to the initial submission.

Version Bump

Always increment the version in manifest.json:

// Semantic versioning recommended
{
  "version": "1.2.3"  // major.minor.patch
}

Chrome also supports a four-part version: 1.2.3.4. The version must be higher than the currently published version.

Upload and Publish Steps

1. Build your extension ZIP (same process as initial submission)
2. Go to the Developer Dashboard
3. Click on your extension
4. Click “Package” in the left sidebar
5. Click “Upload new package”
6. Upload the new ZIP file
7. Update any store listing fields if needed
8. Click “Submit for review”

Staged Rollout

For updates, you can use a staged rollout:

1. After uploading, select “Publish to a percentage of users”
2. Choose a percentage (e.g., 10%)
3. Monitor crash rates and user feedback
4. Gradually increase the percentage
5. When confident, publish to 100%

This is invaluable for catching issues that only appear at scale.

Automating Uploads

Use the Chrome Web Store API for CI/CD:

# Install the Chrome Web Store CLI
npm install -g chrome-webstore-upload-cli

# Set environment variables
export EXTENSION_ID="your-extension-id"
export CLIENT_ID="your-oauth-client-id"
export CLIENT_SECRET="your-oauth-client-secret"
export REFRESH_TOKEN="your-refresh-token"

# Upload and publish
chrome-webstore-upload upload \
  --source extension.zip \
  --extension-id $EXTENSION_ID \
  --client-id $CLIENT_ID \
  --client-secret $CLIENT_SECRET \
  --refresh-token $REFRESH_TOKEN

chrome-webstore-upload publish \
  --extension-id $EXTENSION_ID \
  --client-id $CLIENT_ID \
  --client-secret $CLIENT_SECRET \
  --refresh-token $REFRESH_TOKEN

Getting API Credentials

1. Create a project in the Google Cloud Console
2. Enable the Chrome Web Store API
3. Create OAuth 2.0 credentials (desktop application type)
4. Use the OAuth playground or a script to obtain a refresh token
5. Store credentials securely (never commit to version control)

Managing Multiple Versions

You can maintain separate release channels for testing and stability.

Release Channels

Setting Up Beta and Dev Channels

Each channel is a separate listing in the Chrome Web Store:

1. Create a new item in the Developer Dashboard for each channel
2. Use a different name to distinguish them (e.g., “My Extension Beta”)
3. Set the visibility to “Unlisted” or “Trusted testers”
4. Use the update_url in the manifest to point to the correct channel

Trusted Testers

For beta testing with a controlled group:

1. In the Developer Dashboard, go to “Distribution”
2. Select “Trusted testers”
3. Add tester email addresses (they must have Google accounts)
4. Only these users can see and install the extension

Version Numbering Across Channels

Stable:  1.2.0
Beta:    1.3.0-beta.1
Dev:     1.4.0-dev.1

Chrome only compares the numeric version parts (1.2.0 vs 1.3.0). The suffixes are for your internal tracking – they do not appear in the manifest.

Analytics Dashboard and User Metrics

The Developer Dashboard provides analytics for each published extension.

Available Metrics

Interpreting Key Metrics

Install rate (installs / impressions) is your most actionable metric:

• Below 5%: Your listing needs work (screenshots, description, or too many permission warnings)
• 5-15%: Average for most extensions
• Above 15%: Strong listing with good conversion

Uninstall rate: If more than 5% of users uninstall within the first week, investigate:

• Does the extension work as described?
• Is the onboarding clear?
• Are permission warnings scaring users after install?
• Are there performance issues?

External Analytics

For deeper insights, integrate your own analytics:

// Minimal, privacy-respecting analytics
async function trackEvent(event: string, properties?: Record<string, string>) {
  // Only track if user has opted in
  const { analyticsOptIn } = await chrome.storage.sync.get('analyticsOptIn');
  if (!analyticsOptIn) return;

  await fetch('https://your-analytics-endpoint.example.com/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      event,
      properties,
      extensionVersion: chrome.runtime.getManifest().version,
      timestamp: Date.now(),
    }),
  });
}

Always provide an opt-out mechanism and disclose analytics in your privacy policy.

Handling User Reviews and Support

User reviews directly affect your store ranking and install rate.

Responding to Reviews

You can reply to reviews from the Developer Dashboard:

• Positive reviews: Thank the user briefly. Mention upcoming features if relevant.
• Bug reports in reviews: Acknowledge the issue, ask them to contact support with details, and provide your support email or link.
• Negative reviews: Respond professionally. Address the specific complaint. If you fix the issue, reply again asking if they would consider updating their rating.
• Spam or abusive reviews: Report them through the Dashboard. Do not engage.

Support Channels

Provide clear support channels in your store listing:

1. Email: Simple and universal. Include a dedicated support email.
2. GitHub Issues: Good for developer-oriented extensions. Users can search existing issues before reporting.
3. FAQ/Help page: A web page answering common questions reduces support volume significantly.
4. In-extension help: Add a help section or link in the extension’s popup or options page.

Managing Expectations

Set expectations about response time in your listing:

SUPPORT:
Email: support@example.com
Response time: Within 48 hours on business days

For bug reports, please include:
- Chrome version (chrome://version)
- Operating system
- Steps to reproduce the issue
- Screenshots if applicable

Monetization Options

The Chrome Web Store supports several monetization models.

Freemium

The most common model for Chrome extensions:

• Free core features available to all users
• Premium features gated behind a subscription or one-time purchase
• Handle license validation in your service worker

interface License {
  tier: 'free' | 'pro' | 'team';
  expiresAt: number | null;
  features: string[];
}

async function checkLicense(): Promise<License> {
  const { licenseKey } = await chrome.storage.sync.get('licenseKey');

  if (!licenseKey) {
    return { tier: 'free', expiresAt: null, features: ['basic'] };
  }

  const response = await fetch('https://api.example.com/license/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ key: licenseKey }),
  });

  return response.json();
}

function isFeatureAvailable(license: License, feature: string): boolean {
  return license.features.includes(feature);
}

One-Time Payment

Charge once for lifetime access:

• Simpler for users to understand
• No recurring revenue (limits long-term development funding)
• Use a payment provider (Stripe, Gumroad, LemonSqueezy) for licensing
• Deliver a license key after purchase

Subscriptions

Recurring revenue model:

• Monthly or annual billing
• Requires a backend to manage subscriptions
• Use Stripe, Paddle, or a similar provider
• Handle grace periods for failed payments
• Provide clear cancellation instructions

Implementation Considerations

• License validation: Check server-side, cache locally, re-validate periodically
• Offline access: Decide how premium features work when offline
• Grace periods: Do not immediately disable paid features on payment failure
• Refund policy: State it clearly in your listing
• Trial periods: Allow users to try premium features before paying

Chrome Web Store Payments (Deprecated)

The Chrome Web Store’s built-in payment system (Chrome Web Store Payments) has been deprecated. Use third-party payment providers instead.

Transferring Extension Ownership

Extensions can be transferred between developer accounts.

When to Transfer

• Selling an extension to another developer or company
• Moving from a personal account to a company account
• Team member leaving who owns the developer account
• Merging multiple developer accounts

Transfer Process

1. Contact Chrome Web Store support: There is no self-service transfer. Email chromewebstore-dev-support@google.com with:
   • Extension ID
   • Current owner’s developer account email
   • New owner’s developer account email
   • Confirmation from both parties
2. Requirements:
   • Both accounts must be verified developer accounts
   • The new owner must have paid the $5 registration fee
   • The new owner must agree to maintain the extension’s policies
3. What transfers:
   • The extension listing and all its versions
   • User base and install count
   • Reviews and ratings
   • Analytics history
4. What does not transfer:
   • Revenue from the old owner’s payment provider
   • OAuth credentials and API keys (you must set up new ones)
   • Support email settings (update these in the listing)

Group Publishing

To avoid the need for transfers when team members change, use group publishing:

1. Create a Google Group for your development team
2. Register the group as the publisher in the Developer Dashboard
3. Add or remove team members from the group as needed
4. The extension is owned by the group, not any individual

This is the recommended approach for any organization or team.

Before You Transfer

• Back up all source code (the Chrome Web Store does not let you download previously uploaded ZIPs)
• Document all API keys, OAuth credentials, and service accounts
• Notify your users about the ownership change in the extension’s changelog
• Update the privacy policy to reflect the new owner’s information
• Transfer any associated domains, analytics accounts, and support channels

Summary

Publishing to the Chrome Web Store is a multi-step process that rewards preparation. Register your developer account early, invest in your store listing, minimise permissions, write a real privacy policy, and plan for the review timeline. Once published, use staged rollouts for updates, monitor your analytics, respond to user reviews, and choose a monetization model that matches your extension’s value. Keep your listing accurate, your permissions minimal, and your users informed – that is how you build a successful Chrome extension. -e —

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.