Building your first integration marketplace is tough! You want to have as many useful apps in it as possible, but you also need to keep the quality high. And no matter how you do it, you’re going to need your developers to do some work for you to build out their listing.
At Relay.app, we’re in the integration business, so we’ve gone through the process of getting listed in many, many marketplaces (Slack, HubSpot, Intercom, Linear to name a few). In this blog post, we’ll share what we’ve learned, so that you can craft a developer-friendly experience for your marketplace submissions. Whether you are a platform owner, product manager, or developer advocate, understanding how to streamline and simplify your requirements can make a world of difference in attracting and retaining the developer community.
1. Keep your requirements succinct
Ensure your requirements are concise, offering developers a streamlined checklist of essential information that can be promptly provided. Below is a curated list of fundamental requirements:
- App Name
- Company Website
- App Logo - Include specifications such as file types and dimensions
- App Tagline - Include any word limit (e.g. < 50 characters)
- App Description - Include any word limit (e.g. <300 characters)
- Screenshots - Include the number of required screenshots, the filetypes and dimensions, and any guidelines about whether they should be product-only or if they can also have explanatory text.
- Support Contact Information
- Getting Started Instructions for Users - Include the preferred format of these getting started instructions.
- Integration Testing Instructions for Approvers - Include the process you want developers to follow for setting up your test accounts and validating the integration.
Optional additions - These all add value without being too burdensome for developers.
- Pricing Information
- Privacy Policy URL
- Terms of Service URL
- Demo Video
- Required OAuth Scopes
By sticking with these items and making your preferred formats and lengths totally clear, you can not only make the submission process smoother for developers, but you also ensure that your marketplace listings are clear and effective for your customers.
Example submission forms:
To make things concrete here are a few that we liked:
- Harvest form
- A shining example of clarity and conciseness.
- Inline instructions seamlessly guide developers through requirements.
- Lever form
- Though it demands a bit more detail, the form maintains a developer-friendly approach.
- Linear form
- Despite its Google Form format, the Linear form includes clear inline instructions in each of their fields.
- They also included a sample listing which serves as a great guide.
Harvest form
Linear form
2. Provide clarity on the overall process
Beyond the specific requirements, it’s helpful to give developers a birds-eye view of the process. This is best done with a separate overview page that’s linked everywhere for easy reference.
Consider incorporating the following into your overview page.
- Clear process and timeline expectations
- Set the stage by defining the review process expectations, including the number of rounds of review and anticipated timelines for each.
- If there are common reasons that apps are not approved, please list them.
- Include a sample listing for reference
- Illustrate excellence by providing a sample listing for developers to emulate.
- Detail how information provided will be used
- Clarify how each piece of information contributes to the final listing display.
- Image specifications and word limits
- As mentioned above, it’s critical to clearly outline any requirements related to image dimensions or resolutions, and the word limits and formats for any text content.
- Field requirements
- Clearly indicate which fields are mandatory to ensure developers cover all bases. For optional fields, add a quick note of why a developer may want to include them.
- Provide contact info for support
- Equip developers with the means to reach out by providing clear contact details for inquiries.
- Call out any common mistakes for rejections
- Preemptively list out any common mistakes that apps get rejected so that developers can double check before submitting for review, e.g. requesting too broad of OAuth scopes, not providing any login info if the app has no free signups.
Example overview pages
- HubSpot listing requirements
- This overview clearly defines what are the minimum requirements, and details process timelines, e.g. “Once you submit your listing, HubSpot will complete an initial review within 10 business days”.
- Intercom listing guidelines
- This is a bit longer but each section is quite succinct and to the point in terms of what is expected and required, making it a breeze for developers to read.
3. Offer detailed and prompt feedback
Upholding high standards for your marketplace listings requires a robust review process, but it’s incredibly frustrating for developers to get unclear feedback, especially if this occurs over multiple rounds with long time lines. Here are some recommendations to make it easy:
a. Implement automatic immediate feedback when possible
When a user submits the requirement form, provide automated errors to highlight deviations from specified requirements. For instance, if screenshots must adhere to specific aspect ratios or resolution sizes, automated detection can promptly flag non-compliance issues.
This proactive approach not only establishes a foundational line of defence in the review process but also offers developers immediate insights. By integrating automatic feedback mechanisms, your marketplace ensures that listings undergo an initial pass, and saves you time in resolving basic errors.
See this example during Slack review—it provides immediate feedback when the wrong information is entered:
b. Give comprehensive feedback
Beyond automated checks, when the approver tests the app and identifies issues, it is crucial to communicate these findings clearly and constructively to ensure a streamlined process.
Provide clear error messages and possible remedies
It can be frustrating when developers get feedback on errors that are vague or don't provide any clear action items. For instance, if the concern revolves around the app requesting broader OAuth scopes than necessary, we should provide a detailed breakdown - clearly outline the specific scopes causing the issue and guide the developer on potential remedies. This may involve explaining how those OAuth scopes are utilized or recommending their removal from the app.
Detail next steps
As part of the feedback, a detailed set of next steps should be provided:
- should the developer re-submit the app review?
- Is it going to restart the entire review cycle?
- What is the new expected timeline for re-review?
Provide a way for developers to ask questions
Be clear on how developers can ask questions regarding the feedback, this can happen quite often as there can be cases where the reviewer has a misaligned understanding on how the integration works on the developer’s app. After all, it’s the developer who knows how their app works the best. So providing a way for developers to raise their questions or have a meaningful discussion with the reviewer will expedite the process.
See this example for feedback from our HubSpot review - they provided clear messaging on what the issues are, links to find out more details, and an email address for developers to ask questions.
By delivering comprehensive feedback, not only do you facilitate issue resolution, but you also empower developers with actionable insights. This collaborative approach fosters a culture of continuous improvement, ensuring that each iteration brings marketplace listings closer to excellence.
Conclusion
Crafting a seamless and developer-friendly experience in your marketplace listings will not only make the process easier for developers, it will yield a higher quality marketplace for you. By following the advice above, you can pave the way to a much smoother integration experience. If you’re building a new marketplace and are looking for a first developer to test your process, feel free to reach out to us at support@relay.app!
