Plugin Review Guidelines

This document outlines the requirements your Plugin must meet before and during the review process. Use the pre-submission checklist to self-audit before submitting. Plugins that do not meet these guidelines will be rejected with specific feedback for remediation.

---

1. Pre-Submission Checklist

Complete every item before submitting your Plugin for review:

General Requirements

• Plugin is fully functional — no crashes, infinite loops, or dead-end states
• Privacy policy URL is valid, publicly accessible, and describes data handling practices
• Support URL is active and leads to a functional support channel
• Documentation URL exists and covers installation, configuration, and basic usage
• Description is accurate, complete, and free of misleading claims

Assets and Listing

• Plugin icon provided (512 x 512 px minimum, PNG or SVG)
• Minimum 3 screenshots provided (1920 x 960 px, showing real functionality)
• Screenshots are current and accurately represent the Plugin
• Pricing is transparent — no hidden fees or undisclosed in-plugin charges
• Category selection is appropriate for the Plugin's functionality

Security and Data

• Test credentials provided for the reviewer (separate from production credentials)
• Webhook signatures validated on every incoming webhook
• OAuth scopes are minimal — only request access that the Plugin actively uses
• No hardcoded secrets, API keys, or credentials in source code
• Data deletion logic implemented for Plugin uninstallation

User Experience

• All API errors handled gracefully with user-friendly messages
• Loading states implemented for all asynchronous operations
• No raw stack traces, error codes, or debugging output shown to users
• Plugin functions correctly when installed on a store with no prior data

---

2. Technical Requirements

2.1 Performance

2.2 Security

• Transport Security: All external requests must use HTTPS (TLS 1.2 or higher).
• Input Validation: Sanitize all user inputs. Validate all data received from webhooks and APIs.
• Webhook Verification: Verify webhook signatures using the shared secret. Reject unsigned or tampered payloads.
• Token Storage: Store OAuth tokens securely. Never expose tokens in client-side code, URLs, or logs.
• Content Security Policy: Plugin iframes should implement appropriate CSP headers.
• Dependency Security: No known critical or high-severity vulnerabilities in dependencies at time of submission.

2.3 API Usage

• Respect all documented rate limits.
• Cache responses where appropriate to reduce API load.
• Use pagination for list endpoints — do not attempt to fetch all records in a single request.
• Handle API deprecation notices and migrate within the communicated timeline.
• Only access data within the scopes granted by the Store Owner.

2.4 Reliability

• Implement idempotent webhook handlers — the same webhook delivered twice must not cause duplicate actions.
• Handle network failures gracefully — display clear messaging when the Plugin cannot reach its backend.
• Implement health checks if your Plugin depends on external services.

---

3. UX and Design Requirements

3.1 Design Tokens

Plugins rendered within the Whatalo admin should respect the platform's design language:

• Use the Whatalo CSS custom properties (design tokens) for colors, spacing, and typography when rendering inside the admin iframe.
• Maintain visual consistency with the admin dashboard — your Plugin should feel like a natural extension of the platform.
• Avoid overriding global styles or injecting CSS that bleeds outside your Plugin's container.

3.2 Accessibility

Plugins must meet WCAG 2.1 Level AA compliance:

3.3 Responsive Design

• Plugin interfaces must be functional at viewport widths from 768px to 1920px.
• Critical functionality must be accessible on tablet-sized viewports (768px minimum).
• Avoid horizontal scrolling within the Plugin iframe at any supported viewport width.

3.4 Empty States

• Provide meaningful empty states when no data is available.
• Include clear calls to action that guide the user on how to get started.
• Never show a blank screen or generic "no data" without context.

---

4. Content and Listing Quality

4.1 Naming

• Plugin names must be unique within the Marketplace.
• Names must not contain the word "Whatalo" unless explicitly authorized.
• Names must not be misleading about the Plugin's functionality or origin.
• No excessive capitalization, special characters, or emoji in the Plugin name.

4.2 Description

• First sentence must clearly state what the Plugin does.
• Include key features as a bulleted list.
• Specify any external service dependencies or additional accounts required.
• If the Plugin requires configuration in an external system, describe the setup process.
• Do not include promotional language, competitor comparisons, or unverifiable claims.

4.3 Screenshots

• Must show the actual Plugin interface, not concept art or mockups.
• Should demonstrate core functionality and key user flows.
• Text in screenshots must be legible.
• Include captions or annotations if the functionality is not self-evident.

4.4 Pricing Transparency

• Clearly state what is included in each pricing tier.
• Disclose any usage limits, feature restrictions, or fair-use policies.
• If the Plugin integrates with a paid external service, disclose the additional cost.

---

5. Review Process

5.1 Timeline

5.2 What Reviewers Check

Reviewers evaluate your Plugin against the following areas:

1. Functionality — Does the Plugin work as described? Are there crashes or broken features?
2. Security — Are credentials secured? Are webhooks verified? Is data access minimal?
3. Performance — Does the Plugin load quickly? Are API calls efficient?
4. User Experience — Is the interface intuitive? Are errors handled gracefully?
5. Accessibility — Does the Plugin meet WCAG 2.1 AA requirements?
6. Listing Quality — Is the description accurate? Are screenshots current?
7. Policy Compliance — Does the Plugin comply with the Terms of Service and Acceptable Use Policy?

5.3 Review Outcomes

---

6. Rejection and Re-Submission

6.1 Common Rejection Reasons

1. Plugin crashes or has critical bugs during testing.
2. Security vulnerabilities (hardcoded secrets, unverified webhooks, excessive scopes).
3. Missing or non-functional privacy policy, support, or documentation URLs.
4. Plugin functionality does not match the listing description.
5. Poor user experience (no loading states, raw error messages, broken layouts).
6. Accessibility failures (no keyboard navigation, insufficient color contrast).
7. Rate limit violations or inefficient API usage patterns.
8. Misleading Plugin name, description, or screenshots.
9. Plugin duplicates core Platform functionality without adding meaningful value.
10. Insufficient test coverage or reviewer unable to test the Plugin with provided credentials.

6.2 Re-Submission

• You may re-submit after addressing all issues cited in the rejection feedback.
• Include a change log explaining what was fixed in your re-submission notes.
• Re-submissions enter the review queue but receive priority (typically 3-5 business days).
• After three (3) consecutive rejections for the same Plugin, a mandatory 30-day cooling-off period applies before the next submission.

6.3 Appeal Process

If you believe your Plugin was incorrectly rejected:

1. Submit an appeal through the Developer Portal within fourteen (14) calendar days of the rejection.
2. Include a detailed explanation of why you disagree with the rejection.
3. A senior reviewer (different from the original reviewer) will re-evaluate your submission.
4. Appeal decisions are final and will be communicated within ten (10) business days.

---

7. Updates to Published Plugins

7.1 What Requires Review

7.2 Emergency Patches

If your Plugin has an active security vulnerability:

1. Contact Whatalo Developer Relations immediately.
2. Submit the patch with a "Security Fix" flag.
3. Security patches receive priority review (target: same business day).

---