Start typing to search...

2021 updates

This digest summarizes updates to the Koji platform, packages, and developer site from earlier in 2021. For the latest updates, see developer-updates.html.

If you have thoughts, questions, or feedback, please reach out to the developer community or the @Koji-Team on our Discord server.


Developer site updates

Koji platform updates

  • The platform navigation has been updated to support the Koji Profile as a central home for a creator’s Koji apps. Related changes include:

    • The Koji button has been replaced with a new floating menu on profiles and a top navigation bar on app. This new navigation is less invasive and brings the experience of managing a profile or app much close to the app itself.

    • Creators can no longer remix apps directly. Instead, when viewing someone else’s app, creators can tap the app name to view the App Store listing and preview or use the app from there.

      App Store listing
  • You can now make withdrawals from your Koji account without any fees, so you can retain more revenue from your apps.

  • For security reasons, your Koji wallet no longer allows topping up. The Koji wallet appears as a payment option only for a creator who has received funds. For other users, the Koji wallet will no longer be visible.

  • Fixed a bug where custom controls would show a loading indicator but would never load.

  • Fixed a bug where product SKUs were not correctly resolved on the backend unless they were all lowercase. Product SKUs are no longer case-sensitive.

  • The estimatePoses option is no longer supported for video captures. Apps can process camera input directly, if needed.

  • The following contexts and associated entitlements have been deprecated: admin, about, and sticker. Apps can provide admin interfaces by managing roles with the Identity class in the @withkoji/core package.

  • The FeedEvents entitlement has been deprecated.

Core package updates

  • In the withkoji-koji-core.html package, the new metadata object provides a reference to the creator’s current username and profile picture. Apps no longer need to collect this data from the user as a configuration option, and users can update their information at the platform level and have it automatically applied in all apps.

    At runtime, these values are managed by two new environment variables: KOJI_CREATOR_USERNAME and KOJI_CREATOR_PROFILE_PICTURE.

  • Apps can use the new iap.refundTransaction method to refund unsettled transactions.

  • Apps can use the new ui.present.systemAlert method to communicate state changes to users.


New developer game tutorials

On the developer site, a new set of tutorials are available to help developers quickly learn how to build games on Koji.

Integrated Core reference docs

The reference documentation for the @withkoji/core package is now integrated into the Koji developer site.

  • All of Koji’s developer documentation in one place – search everything to find what you need.

  • Deep links from the reference documentation to the related package code on Github.

  • Organized by class for easier navigation with less clicking.

  • Updated code examples for all methods.

Core package updates

The following features are now available in the @withkoji/core package.

For a comprehensive list of changes and versions, see the package release notes in Github.

Freeze Keys for data caching

Freeze Keys enable you to cache and purge content in Koji’s CDN, dramatically improving the speed and reliability of backend data requests in your Kojis.

  • Make a request directly to the Koji CDN and receive a cached response, instead of waiting for the backend to warm up and serve the request.

  • Use the x-koji-freeze-key header to instruct the CDN to serve a cached response and KojiBackend.Utilities.unfreeze to reset the cache.

  • Manage multiple routes and cache endpoints.

  • The platform automatically handles remix scoping, so you can maintain one set of logic in your templates.

File uploads from Koji frontends

The new Koji.ui.upload class enables file uploads from the frontend of your Koji directly to your project’s CDN. You can use this method to upload media created or captured by the user as part of the template experience. For example, recording a video or drawing on a canvas.

Additional changes

  • Define products that hold transactions in a pending state until you manually capture them.

  • Add watermarks or specify cropping constraints for uploaded videos.

  • Various fixes and features to improve the usability and functionality of the Core package methods.

Koji platform updates

Developer experience enhancements for in-app purchases

  • In-app purchase products are now registered or updated on any deploy, instead of only when you publish the template from the Koji editor.

  • In the debugger, you can now drill into the details of in-app purchase products and receipts. This feature improves debugging for product definition updates, as well as for the use of custom attributes on receipts.

Analytics and usability improvements

  • Live analytics are now available for your Kojis. To see a live count of users (accurate to within 20 seconds), simply tap the Koji button on any of your Kojis.

    Live analytics
  • The main menu, which appears when you tap your profile picture, now shows lifetime views and revenue for your Kojis, as well as more clearly calls out your pending balance.

  • On the Your Kojis page, the Revenue chart now provides the same interactive controls as the Views chart.

  • The color picker control now saves your three most recently used colors.

  • Tapping Cancel or Back when editing a Koji now returns to the Koji instead of the home page.

  • The Koji editor has improved performance for a better experience when editing your code.

Changes to withdrawals, refunds, and fees

  • Template developers can now determine the fee percentage for in-app purchases in their templates. The developer receives 60% of the fees collected for all of these transactions.

  • Automatic withdrawals are now available for some countries outside the US. If automatic withdrawals are not supported for your country, you can contact the Koji team and we can process your withdrawal manually.

  • For refunds of purchases made with a credit or debit card, the balance is now refunded to that debit or credit card, instead of your Koji wallet.

  • Evolution/lineage payments are no longer applied.

  • Paid subscriptions are no longer available.

Bug fixes

  • Changing your username from account settings now correctly regenerates your profile.

  • Editing a Koji now correctly updates its thumbnail or sharing image. Sharing images that were previously cached by other services, such as iMessage or Facebook, still might not update.

  • In the Project Details page, builds now show when they are completed without the need to refresh the page. Also, build logs now live stream correctly.

  • Links to pages on the that are not Kojis no longer open in popover views.

  • Various layout and styling fixes.


March 17

  • The following usability improvements are now available on the Koji platform.

    • Creators can now automatically upgrade their Kojis to the latest version of your code. When an upgrade is available, the creator can tap Upgrade this Koji on the Koji’s analytics page.

    • Your Koji profile page has been updated to a new link-in-bio profile that is powered by a Koji template. The new profile builder features fully customizable backgrounds, buttons, and fonts and provides the same powerful analytics that are built into your Kojis.

    • The navigation experience in Kojis has been improved with updates to the modal windows for embedded Kojis, removal of the confirmation prompt when linking to another website, and support for links.

    • The onboarding flow for new users has been redesigned for a better welcome experience to Koji.

    • The experiences for publishing a remix, using asset packs and associated editing tools, and selecting a color have been redesigned for better usability. System alerts and the loading spinner have also been updated.

    • The Koji theme is no longer available as an account setting. If your device is set to dark mode, Koji displays in dark theme mode. Otherwise, Koji displays in light theme mode.

    • A custom magic link is no longer available as an account setting. Instead, your new Koji profile is available the from an automatic link at Existing magic links will continue to work; however, they cannot be updated.

  • Paid remixes are a new way for developers to monetize their work through Koji. You can set the remix price when you publish a template in the store, and then earn when someone remixes your template.

  • The koji VCC type has been renamed to the link VCC type. The link type now supports an extended result format, which returns the page title, description, and a thumbnail URL that is hosted on the Koji CDN.

  • You can now hide the default action for cancelling a remix, enabling the template to implement its own navigation controls. To hide the default action, enable the new InstantRemixingNativeCancel entitlement. To implement a custom cancel action, use the new remix.cancel method in the @withkoji/core package.

  • The following features are now available in the @withkoji/core package.

    • The new ui.navigate.edit method enables a template to programmatically enter an edit experience.

    • In PlayerState, two new methods (onFocus and onBlur) and one new property (hasFocus) enable templates to respond to the focus state of the Koji.

    • In Database, for any method that updates a database entry, an optional returnDoc parameter returns the updated entry.

    • Koji.ui.capture.sound has been replaced with Koji.ui.capture.koji has been replaced with

    • The identity.getToken method now returns a presumedRole that can be used in frontend services to provide owner or admin actions in a Koji. Admin actions must still be secured on the backend by resolving the user’s role.

    • The secret.generateSignedUrl method now supports securing URLs with query string parameters.

    For a comprehensive list of changes and versions, see the package release notes in Github.

March 2

  • On the developer site, a new set of quick start tutorials are available to help developers get going quickly on Koji.

  • The Koji Support page is now available for logging bugs and requests with the Koji team. This short form enables better tracking and quicker resolution of problems.

    For the quickest answers to general questions, continue to check out the Help Center or connect with the community on Discord.

  • The following features are now available in the Template Store.

    • Template creators can now see the number of remixes and the revenue for their template.

    • Creator usernames are now visible on templates.

    • New actions are available from the menu on the Template Details page – Share, for every template, and Manage Template, for your templates.

      Template Details page
  • The following features are now available on the Koji platform.

    • The developer portal now shows projects that have a running editor in a separate section.

    • The color VCC now validates the color string before returning a value.

    • The Koji editor now shows a confirmation prompt before closing the browser tab.


February 22

  • In the Template Store, the new Variants feature enables better template discovery. With this new feature, template developers can curate a list of related templates. For example, provide a version that includes email capture alongside a version that does not.

  • The Template Details view is now available for community-developed templates.

    • To create a new template, go to the developer portal and click My Templates. You can define and manage the details for your templates, including the base Koji, descriptive text, videos, screenshots, and variants.

    • To submit your template for consideration in the Template Store, send it to the Koji team for review. Approved templates will be featured in the appropriate category on the store page.

  • A new guide is available to help you upgrade your code to the @withkoji/core package. See migrate-koji-core.html.

  • The following features are now available in the @withkoji/core package.

    • You can now use initialValue to set a starting value for color, range, and select captures.

    • The new frontend/navigate module provides methods for controlling navigation in your Kojis.

    • The new custom method in frontend/capture enables you to capture values with custom VCCs.

    • Fixed various issues.

    For a comprehensive list of changes and versions, see the package release notes in Github.

  • The values of the KOJI_PROJECT_ID and KOJI_PROJECT_TOKEN environment variables are now available from Project Details, making it easier to set up your local development environment.

  • The Koji button and user profile menu have been redesigned for clarity and usability. New styles and menu options improve the experience of navigating around the Koji platform.

  • Remix states (defined in quickstart.json) and the onSetCurrentState method are no longer supported on the platform.

February 1

  • The Koji developer community has a new channel. You can watch the welcome video here.

  • The new @withkoji/core package includes everything you need to easily access platform services in your Kojis.

    • Implement core platform features in your Koji template, including remixing, in-app purchases, UI controls, messaging, and identity services.

    • Use straightforward methods that are scoped for frontend or backend services, with less boilerplate code.

    • Manage remix data with greater flexibility, without the need for specialized JSON customization files.

    • As part of this change, many existing packages are now deprecated. Deprecated packages are still available for backwards compatibility; however, developers are encouraged to use the new core package for all new projects and updates going forward.

  • To enhance the developer experience, the following updates are now available on the Koji platform.

    • The Koji editor now uses the same live preview as the debugger, for seamless testing during development.

    • The publishing page in the Koji editor has been redesigned for a more streamlined experience.

    • The Koji editor and Project Details have been updated with more help text and improved styling for better usability.

  • The new Template Details page provides a place for remixers to learn about a template before they create their own version.

    • To make a new Koji from the Template Details, tap Remix, or tap Preview and then Remix.

      Template Details page

      This view is currently available for Koji-provided templates, and it will be rolled out to community-developed templates over the next few releases.

    • For a catalog of available templates, go to


January 15

  • For template developers, the following features are now available on the Koji platform.

    • The new media VCC provides a single control for customizing image, file, sound, and video values. You can configure which of the underlying media types to allow as well as the options for each type. As part of this change, the image VCC now supports type options for all Fastly parameters, enabling you to automatically manipulate uploaded images.

    • The new @initialTransform key for JSON customization files enables templates to reset specific VCC values when a new remix is created. For example, in templates for selling items, you might want to reset the product name and description to placeholder text. See Visual Customization Controls (VCC).

    • To improve stability and protect against bursts of traffic, requests to Koji backends are now rate limited to 900 requests, per 15 minutes, per IP address. Rate limits are applied per remix, so a user could make up to 900 requests each to multiple Koji backends in 15 minutes. Users who send too many requests in quick succession might see error messages with a status code of 429.

    • To improve performance, the Koji debugger now debounces value updates.

  • In the withkoji-database-package.html package, the new increment method provides an atomic operation for incrementing numeric values in the database with a single update request.

  • For all creators, the following usability enhancements are available on the Koji platform.

    • The new Manage this Koji button appears across the top of any Kojis you create and provides easy access to at-a-glance insights and settings.

    • The sharing menu has been updated.

    • Your Koji profile page is now available from the following automatic links: and

      (where name is your user name on Koji).

    • New caching and performance improvements were added to enhance content delivery.

January 8

  • A new Help Center is now available for finding answers to general platform questions, such as how withdrawals work.

  • For template developers, the following new features and navigation updates are available.

    • The new project overview page lets you access key information about your templates without loading them in the Koji editor. For example, open the debugger, or view the build logs, commit history, and other git info. As part of this enhancement, the My Repositories page has changed to My Projects and has an updated layout. To access the project overview for one of your templates, go to My Projects and click the desired project.

      Project overivew page
    • The new Developer Tools view shows the advanced details and metadata about any Koji. To access it, tap the Koji button, and then tap More > Developer Tools.

    • The new CustomMetadata entitlement enables a custom title and description when sharing a Koji on social media. See thumbnail-image.html.

    • In the withkoji-vcc-package.html package, the new share method enables templates to open the sharing menu.

  • For all creators, the following new features and navigation updates are available.

    • A new dashboard view provides access to information and settings for a Koji you create. To access it, tap the Koji button, and then tap Koji Settings.

    • The built-in Visual Customization Controls (VCCs) were updated with a more streamlined look and feel to improve the remixing experience.

    • Sharing your Koji profile page on social media now renders a rich preview.

  • The following bugs have been fixed.

    • When uploading media in a VCC, it is no longer possible to accidentally dismiss the control and cancel the upload.

    • Lineage now correctly computes all descendants, instead of only the Koji’s children.

    • Scrolling the Koji home page no longer causes templates to load at the wrong scroll offset.