App Plans and Upgrades

A plan relates to the features you deliver to a customer. Plans can be connected to a paid subscription. Every App must have at least one plan, even if it is not a paid application (free). In most cases, when users install an application, they're prompted to select a plan before starting the install. The selected plan is passed along as part of the installation callback.

Subscriptions & Plans

Duda supports a linear plan structure with subscriptions. This means that apps can only have a single active subscription and plan at a time. Users can upgrade to plans when they need to access features that are not available on the current plan.

Plans basics

  1. Each app must have plan(s) in order to be installed on a site.
  2. Each installation must include an active plan.
  3. Plans can be free, trial, or paid.
  4. Free-trial plans are supported on the provider side.
  5. Duda supports a linear plan structure:
  6. Each plan has a grade, an integer.
  7. Users can upgrade from the active plan to plans with higher grade.
  8. Downgrades are currently not supported.

Defining plans in the manifest

Plans are defined in the app manifest, under the app_plans property, using the following format:

"app_plans": [
        {
            "plan_uuid": "332653a3-df51-45ce-a873-fbb0b1ccb49f",
            "plan_type": "FREE",
            "is_hidden": false,
            "plan_grade": 0,
            "plan_profiles": {
                "en": {
                    "plan_name": "First",
                    "plan_subtitle": "Start...",
                    "plan_features": [
                        "My first feature",
                        "<strong>My best feature</strong>",
                        "another feature"
                    ]
                }
            }
        },
        {
            "plan_uuid": "bd50e369-e7d4-4246-83d4-e190038e7f07",
            "plan_type": "PAID",
            "is_hidden": false,
            "plan_grade": 1,
            "plan_profiles": {
                "en": {
                    "plan_name": "Second",
                    "plan_subtitle": "...Finish",
                    "plan_features": [
                        "My first feature",
                        "<strong>My best feature</strong>",
                        "another feature"
                    ]
                }
            }
        }
    ]

Plan properties

Below is a list of each property of the plan's manifest configuration.

📘

Localizing plans

Please pay attention to localizing the profiles of plans. This is required to facilitate the wide adoption of your app.

Property

Type

Description

app_plans

Array of Objects

The entire object that contains details of the App Plans available. Each object in the array is a specific plan.

app_plans[x].plan_uuid

String

A Duda platform wide global identifier for the plan. Plan UUIDs are immutable and generated by Duda.

app_plans[x].plan_type

Enum

Specifies the plan type. Can be either FREE, TRIAL or PAID.

app_plans[x].is_hidden

Bool

The plan is not presented to the user on the plans selection page during install and upgrade flows. Hidden plans are presented as part of the app info under the 'learn more' link in the App Store. The only way to sell this plan is by upgrading to it through the upgrade process triggered by your App.

app_plans[x].is_default

Bool

Default plans will be installed automatically once the user confirm to install the app. Duda will bypass the plan selection screen. Default plans must be free. App cannot have more then one default plan.

app_plans[x].plan_grade

Integer

The logical order in which plans should be displayed. 0 should be your lowest plan, with it incrementing up for each plan higher that you sell.

app_plans[x].plan_profiles

String-object

For each language your application supports, you should fill out the plan profile to correspond with that language.

app_plans[x].plan_profiles["lang"]
.plan_name

String

The unique name of the plan. This will be displayed to users in the UI.

app_plans[x].plan_profiles["lang"]
.plan_subtitle

String

A short description of the plan. For example, who it's good for or what benefit it gives the most.

app_plans[x].plan_profiles["lang"]
.plan_features

Array of Strings

A bullet point list of features which are available in that plan.

Configuring your plans

Not every part of the manifest plan data can be updated by you. This is because, on the Duda side, there are many steps we need to go through in order to set up plans and contracts for selling. Please contact us if you need changes or new plans added.

Supported updates

App partners can do the following by updating the app's manifest:

  • Add/delete localized plan profile
  • Edit the localized plan profiles
  • Change the is_defualt, and is_hidden flags
  • Change the grades
  • Change plan_type from FREE to TRIAL

Unsupported updates

The following cannot be done by app providers:

  • Add/delete plans
  • Change plan UUID
  • Set plan price
  • Change plan_type from FREE or TRIAL to PAID

The above actions can be done only by Duda's team.

Initiating the upgrade flow

The flow of upgrading the active plan of an app can start in several ways.

The user clicks 'upgrade' on the App Store

When the user clicks on upgrade button in the App Store the upgrade flow will start. Duda will present the user a selection screen with all plans with higher grades that are not flagged as hidden.

From the app's iframe via post message

When your app is open within Duda, as an iframe you can send a postMessage from your child frame to the Duda parent.

Duda provides a simple JS SDK/Library for you to use which adds a simple function call to start the upgrade. The URL for this Library is passed as a URL on the SSO to open your app. We recommend relying on this URL to embed the JS library, as we'll update it as we add new options in the future.

To initiate the upgrade flow via Post Message:

  1. Embed the JS SDK in your application page. Duda passes the source of this file as the iframeSDKSrc. Here's an example of it.
  2. Run the function _dAPI.upgrade({planData}), where planData is an object containing configuration for the upgrade flow: appId with your app UUID, type of upgradeApp
  3. You can control the plans the user would see by adding optional parameters:
  4. planId with the UUID of the requested plan: the user will be presented only with that plan. It can be a hidden plan.
  5. plansList with an array of plan UUIDs: the user will be present with the plans passed in the array, including hidden plans passed on the list..
  6. If you don't specify planId or plansList, the user will be presented with the default plan selection screen.

Embedding the SDK

Using the SDK path passed in the SSO link.

<script src={{SDK path sent in the SSO link}}"></script>

Presenting a specific plan

let dudaUpgradeConfig = {
  type: 'upgradeApp',
  appId: 'myApp',
  planId: '4725fcf8-1256-4d5c-803c-69385b565ced'
};

Presenting several plans from a list

let dudaUpgradeConfig = {
  type: 'upgradeApp',
  appId: 'myApp',
  plansList: ['4725fcf8-1256-4d5c-803c-69385b565ced','58b18228-6f9e-4942-bfb5-1d3a06981ce9']
};

Using a deep link

The following deep links will initiate the upgrade flow:

  1. No plan specified:
    https://{dashboard_domain}/home/site/{siten_name}?appstore&appId={app_uuid}&upgrade=true
  2. With a specific plan:
    https://{dashboard_domain}/home/site/{siten_name}?appstore&appId={app_uuid}&upgrade=true&planId={plan_uuid}

See deep links guide.

Upgrade flow UI

📘

Who can upgrade?

Duda's users are divided into two groups:

  1. Staff: web pros who work for web agencies. Also known as Duda aware users.
  2. Clients: the owners of the websites.

Clients are never presented with prices nor asked to confirm payments.
Therefore, when clients start the upgrade flow, Duda would present them with a 'contact your site admin' message.

  1. The upgrade flow starts with Duda presenting the user with a plan selection screen. In case no plan was specified by the upgrade-flow initiator, Duda will present all plans with higher grades that are not flagged as hidden. Duda will also present the active plan as non-selectable to allow the user to compare features.
  2. Depending on the account type, the user is asked to provide/confirm payment details.
  3. Duda presents the user with a progress bar. Meanwhile, Duda sends the app an upgrade callback and waits for a 200 HTTP status code.
  4. Once a 200 response is received, Duda opens the app iframe and directs the user.

Handling upgrade callbacks

Duda sends a callback of the following format to the updowngrade_installation_endpoint listed in the manifest:

{
    "app_plan_uuid": "paln_uuid",
    "recurrency": "MONTHLY",
    "site_name": "1501ccca016a4220861ef07fe2c8eb0d"
}

Duda then waits for the endpoint to respond with a 200 HTTP status code.
As with the installation process, the app can use site-REST API to get information and perform actions while Duda waits for the response.

Setting up a free trial

Duda supports either a free trial or free version of your application. On the Duda side, these are the same mechanism that allows for the free install. If you want to implement a free trial, you will need to lock access to your application after X days (14, 30, etc..) and force the user to upgrade to a higher plan before they get access.

To display a trial plan you should set plan_type to TRIAL with grade 0 and set the default_plan_uuid property of the manifest to this plan. When installing the app via the UI, Duda will not preset the user with a plan selection screen and install the app with the default plan.


Did this page help you?