Extension Development Best Practices
Share your extensions with the world!
There have been more than 30 million unique activations of SketchUp in the last year, with more than 2.5M of them active on a weekly basis. Every second SketchUp is launched by 30 people around the world. Extension Warehouse offers you a way to get your SketchUp Extension into the hands of the entire SketchUp community.
What follows below is a general description of the process of publishing your extension on Extension Warehouse:
- Write some code: Come up with an innovative idea that you think will help SketchUp users. Write some code that makes the idea a reality. Test your code to prove to yourself that it works like you want it to work.
- Build your rbz installer: Build the release-ready RBZ, in accordance with our stated Technical Requirements on this page.
- Upload to Extension Warehouse: Fill out the upload form and include details about your extension that let prospective users know what your code does and whether it would be useful for them.
- Final checks and publication: Check that all your t's are crossed and i's are dotted, hold your breath and punch the "Submit for Review" button.
- SketchUp team review: Our crack team of extension reviewers will check over your submission and validate it against our set of review and acceptance criteria. If something doesn't look right, we'll send you a message explaining what needs fixing before your extension can 'go-live.'
- Ready to Publish: Hooray! Your Extension has made it through Review, and is now ready to be published. We'll email you with the good news once your submission has been approved.
- Publish: At this point, you will need to go back to your “My Extensions” page to publish your extension. It won’t be visible to the public until you have published it.
This section documents the requirements that developers must meet before we agree to publish their extensions on our Warehouse. We may change these requirements from time-to-time in our discretion.
The following are the minimum submission requirements for Extensions offered to SketchUp users through Extension Warehouse. While you may, without question, offer more than what follows, we will accept nothing less. Extensions offered through the Warehouse must be:
- Useful: The extension should provide some useful functionality for SketchUp users.
- Unique: Extensions must not simply duplicate existing features or services of the SketchUp client—they must significantly extend some core feature or add entirely new functionality.
- Functional: Extensions must install and operate as advertised. The extension should not cause SketchUp to crash or perform slowly.
To ensure it's functional and helpful for customers, be sure to review our UX Guidelines as well.
- Safe: The extension should not, through the developer's malice, cause damage to the user's data nor to their operating system.
- Documented: The extension should be documented. The SketchUp team will not document your extension for you.
- Supported: The extension's developer should be available to answer technical support questions after users have installed the extension. The SketchUp team will not offer support to your users.
- Packaged properly as an RBZ Archive: RBZ files are nothing more than ZIP archives of ruby scripts and other assets with a particular, internal folder structure.
- Must not duplicate SketchUp Pro features for SketchUp Make users: Extensions must not duplicate features of SketchUp Pro that are not available to SketchUp Make users. If your extension duplicates Pro features, it needs to meet the "Unique" requirement (see above) and your extension must not work in SketchUp Make.
The following are minimum technical requirements for all submitted Extensions. These are the lines you must stay between in order to have your Extension behave well and operate efficiently within the SketchUp client application.
- Packaging: The Extension Warehouse only accepts RBZ packages. RBZs are simply ZIP files with a different file extension. We have some requirements for what must be inside your RBZs. Inside the root of the rbz package, we only allow a single ruby file that loads your extension, and a folder that contains the rest of your extension files.
NOTE: The folder must have a name identical to the ruby file (without the “.rb” file extension).
- Unique Extension Name: It all starts by choosing a unique name for your extension. Let's assume you're building a plugin called Swivel Driver and your company is called GoCorp. We strongly recommend prepending your extension file names with your initials or company name.
- Namespaces: Wrap all your code in a developer namespace to protect it from conflicts with other developers' scripts.
- Best Practice for "Undo": If your extension adds to or alters the model, it's highly recommended that you wrap these steps in a Model.start_operation / commit_operation call so that users can get their model back with a single Edit > Undo.
The SketchUp team cannot be responsible for supporting users of your extension. You'll need to have some system in place for supporting your users. At a minimum, this includes:
- Documentation: A surprising number of users install SketchUp extensions only to be met with the challenge of locating the new feature(s) in SketchUp's user interface, and figure out how it all works... with no support to do so. A successful extension is one that its users can learn how to use. Don't neglect this step. We highly recommend that you offer on your website’s support page:
Detailed steps for how to get started. Use specific menu names and screenshots if possible.
- A video that shows usage.
- If appropriate, a link to some sample files that allow users to demo the plugin in a "best case" scenario.
- Support contact: Users must be able to contact you for support. Provide a website or a support email address in your account profile links or in your extension description fields.
- Training: While not required, users will appreciate any training videos or other similar materials you can offer them to help get them up the learning curve.
If your extension has dependencies on other code libraries, you need to package them together in your extension package, or provide clear guidance for users telling them how to download and install them.
Reasons We May Reject Your Extension
The truth is, it's possible that your extension might not make it through our review process. If that happens, the reason will hopefully be something minor and easy to fix. The following is a list of reasons we may cite when rejecting an extension. It's intended to serve as a guide for increasing the likelihood of having your extension pass the review process.
Your Extension crashes when used, or causes SketchUp to crash or perform poorly when loaded. If your Extension just plain crashes, it isn't of much use to anyone.
Your Extension causes someone else's extension to crash or perform poorly. Part of participation in the Extension Warehouse is an acknowledgement that you are not doing so in isolation. This thing only really works if everyone stays between the lines.
Your Extension exhibits obvious bugs that prevent it from being used as advertised. Nobody likes code that doesn't work right. It reflects poorly on you and on us. Test your code before submitting it and be sure it does what you think it does.
Your Extension does not perform as advertised. Don't "bait-and-switch" your users. You should describe what your extension does, and deliver that functionality.
Your Extension uses undocumented APIs in SketchUp. Undocumented APIs are unsafe to use because they are subject to change at any time and probably haven't been tested very well. In other words, they may not work tomorrow. And even if they do... they probably won't work well or reliably today because we haven't tested them properly.
Your Extension is a duplicate of someone else's extension. An extension that you claim to be yours shouldn't just be a copy of someone else's work. Be novel, or at least add something new if you are derivative. Don't flat out copy.
Your Extension is spam. Extensions that are simply an advertisement for something else will not be accepted.
It infringes on the trademark, copyright, or patents of another.
It executes malicious code intended to damage another user's computer.
It contains inappropriate, defamatory, obscene, salacious, pornographic or unlawful information, images or materials.
It does not comply with all applicable legal requirements.