Configure entitlements

Entitlements define the configuration settings for the Koji platform features in your app. For example, to allow creators to configure an app, you must enable the InstantRemixing entitlement. To sell products from an app, you must define the product properties, such as name and price, in the InAppPurchases entitlement.

To configure entitlements for your app, define properties and values in the entitlements key of the koji.json file. In your application code, initialize the @withkoji/core package with this configuration data. Publish the app to update the entitlements. The Koji platform applies the entitlement settings to the running app.

The following platform entitlements are available for Koji apps.

Configuration and navigation

To allow creators to configure your app, you must enable the associated entitlement. You can also enable or disable some platform navigation features.

{
  "entitlements": {
    "InstantRemixing": true, (1)
    "InstantRemixingNativeNavigation": true, (2)
    "InstantRemixingNativeCancel": true (3)
  }
}

InstantRemixing – Boolean, Allows creators to configure the app (remix context). Default is false. To determine the current context of a running app, use Koji.playerState.context.
InstantRemixingNativeNavigation – Boolean, Hides the platform action for advancing from a configuration to a preview, so that the app can provide this action. Default is false.

Note
If this entitlement is enabled, the app must use Koji.remix.finish to advance to the preview.
InstantRemixingNativeCancel – Boolean, Hides the platform action for cancelling a configuration, so that the app can provide this action. Default is false.

Note
If this entitlement is enabled, the app must use Koji.remix.cancel to implement a custom cancel action.

Custom metadata

To enable custom metadata when sharing the app, configure the CustomMetadata object.

{
  "entitlements": {
    "CustomMetadata": {
      "enabled": true, (1)
      "metadata": {
        "title": "{{remixData.title}}", (2)
        "description": "{{remixData.description}}" (3)
      }
    }
  }
}

CustomMetadata.enabled – Boolean, Enables the app to use custom metadata when the creator shares it. Default is false.
CustomMetadata.metadata.title – String, Title or path to the creator’s custom title (og:title).
CustomMetadata.metadata.description – String, Description or path to the creator’s custom description (og:description).

In-app purchases

To enable financial transactions in the app, configure the InAppPurchases object.

{
  "entitlements": {
    "InAppPurchases": {
      "enabled": true, (1)
      "products": [ (2)
        0 : {
          "sku": "productID", (3)
          "name": "{{scope.nameKey}}", (4)
          "price": "{{scope.priceKey}}", (5)
          "priceIsUnset": false, (6)
          "quantity": "{{scope.quantity}}",(7)
          "fulfillment": "email", (8)
          "isConsumable": true, (9)
          "dynamicReceipt": true, (10)
          "dynamicReceiptCta": "View Items", (11)
          "captureOnPurchase": false, (12)
          "captureExpiryPeriod": 1 (13)
        }
      ]
    }
  }
}

InAppPurchases.enabled – Boolean, Enables in-app purchases. Default is false.
InAppPurchases.products – Array, Array of objects defining each product that is available for purchase. Products are registered or updated when the app is deployed.
InAppPurchases.products[index].sku – String, Unique identifier for the product. Used to look up the product when the user makes a purchase and to resolve receipts on the backend of the app.
InAppPurchases.products[index].name – String, Name displayed when a user is prompted to purchase the product. Can be a path to the creator’s custom name.
InAppPurchases.products[index].price – Number, Price of the product in USD, if the product has a set price. Can be a path to the creator’s custom price. To register a product with a set price, this value must be greater than 0. To define a product without a set price, enable priceIsUnset instead.
InAppPurchases.products[index].priceIsUnset – Boolean, Defines a product without a set price. For example, a donation or pay-what-you-want price. Default is false. To define a product with a set price, use price instead.
InAppPurchases.products[index].quantity – Number, Maximum number of times the product can be sold. After the inventory threshold is reached, further purchase attempts will display a “sold out!” message. If quantity is not present or is 0, the product will never sell out.
InAppPurchases.products[index].fulfillment – String, User information to collect for order fulfillment. Possible values are email, phone, or address. This value is stored as a custom attribute on the transaction receipt.
InAppPurchases.products[index].isConsumable – Boolean, Enables the product to be purchased more than once.
InAppPurchases.products[index].dynamicReceipt – Boolean, Enables the transaction receipt to display the receipt context of the app. If enabled, use Koji.playerState.context to detect the receipt context, and use Koji.playerState.receiptType to determine whether the buyer or the seller is viewing the receipt.
InAppPurchases.products[index].dynamicReceiptCta - String, A call to action to display on the receipt. If not set, "View Order Details" will be used as the call to action.
InAppPurchases.products[index].captureOnPurchase – Boolean, Indicates whether to capture transactions immediately. Default is true. If set to false, transactions are held in a pending state until they are manually captured with Iap.captureTransaction on the backend of the app. Funds are not available in the seller’s account until the transaction is captured. If you do not capture the transaction within the captureExpiryPeriod, the transaction is automatically reversed and the buyer is refunded.
InAppPurchases.products[index].captureExpiryPeriod – Number, Period within which a pending transaction must be captured before it is reversed, from 0 to 7 days. Default is 0.

Smart contract source maps

To enable automatic contract verification and source mapping for Web3 apps, enable this entitlement.

{
  "entitlements": {
    "SmartContractSourceMap": {
      "enabled": true, (1)
      "compilerInputSource": "frontend/artifacts/build-info/65fb...7f6.json", (2)
      "contractName": "KojiToken", (3)
      "entryPath": "contracts/Token.sol", (4)
      "version": "0.8.2+commit.661d1103" (5)
    }
  }
}

SmartContractSourceMap.enabled – Boolean, Enables the app to verify and map contract sources when deployed. Default is false.
SmartContractSourceMap.compilerInputSource – String, The path in your project where Solidity compiler inputs can be found. This is usually generated automatically by tools like Hardhat. See Solidity Documentation for more details.
SmartContractSourceMap.contractName - String, The name of the contract bundled in your project.
SmartContractSourceMap.entryPath - String, The entry path for the contract, as it appears in your input source.
SmartContractSourceMap.version - String, The full name of the Solidity version used to compile your contract. This is used when Koji’s verifier compiles your contract. If this does not match the version used when you compiled your contract, your contract will not verify.