Getting Started Tutorial

This step-by-step tutorial is designed to get you started with core concepts of the Duda App Store. You'll learn: accessing the App API, Authenticating to a Duda Site, Configuring the App Manifest, and managing the life cycle of your app.

After completing the steps in this guide you'll be able to:

  • Handle installation events once your App is installed by a Duda user
  • Handle upgrades events of plans
  • Revoking access if a user uninstalls your App
  • Authenticating users into your App Dashboard via SSO
  • Perform API calls against the sites on which your App is installed

1. Things you need to get started

To use this guide you need:

  • User name and password to log in to Duda's UI on the Sandbox Environment
  • App account authentication: username and password
  • Your app UUID

If you don't have these, please contact [email protected].

2. Get the App Manifest

We'll start by getting the full App manifest for your application. The App Manifest contains all of your application configuration options within Duda.

Use this API call to get the details of your app from the Duda App Store:

curl -X GET https://api-sandbox.duda.co/api/integrationhub/application/{{appUuid}} -u 'APIUser:APIPass' -H 'Content-Type: application/json'

📘

Basic authentication

All API calls to the Duda App Store require the Authentication header to be present. This authenticates that you are the owner of the App in question. Most other API calls also require a resource token to access the specific site.

The response will include your App manifest details in the following format:

{
    "uuid": "2257f749-03a7-45c2-9e8a-ae5f5e6e072c",
    "webhooks": {
        "endpoint": "https://temporary.com/endpoint",
        "events": [
            "CONTENT_LIB_CHANGED",
            "CONTENT_LIB_PUBLISHED",
            "PUBLISH"
        ]
    },
    "scopes": [
        "GET_WEBSITE",
        "UPDATE_PAGES",
        "SITE_WIDE_HTML",
        "GET_PAGES"
    ],
    "public_key": "KEY-XXXX",
    "installation_endpoint": "https://temporary.com/endpoint",
    "uninstallation_endpoint": "https://temporary.com/endpoint",
    "updowngrade_installation_endpoint": "https://temporary.com/endpoint",
    "base_sso_url": "https://temporary.com/sso",
    "supported_locales": [
        "en"
    ],
    "app_profile": {
        "en": {
            "app_name": "Display name",
            "app_logo": "https://temporary.com/imageLogo.png",
            "app_short_description": "A short description goes here.",
            "app_long_description": "This app can do this a that",
            "public_page": "https://temporary.com/ourproduct",
            "terms_of_service_page": "https://temporary.com/terms_en",
            "privacy_note_page": "https://temporary.com/privacy_en",
            "app_screenshots": [
                {
                    "image_url": "https://temporary.com/image.jpg",
                    "alt_text": "Description of image above"
                },
                {
                    "image_url": "https://temporary.com/image2.jpg",
                    "alt_text": "Description of image above"
                }
            ]
        }
    },
    "wl_app_profile": {
        "en": {
            "app_name": "White Labeled display name",
            "app_logo": "https://temporary.com/imageLogo.png",
            "app_short_description": "A short description goes here.",
            "app_long_description": "This app can do this a that",
            "app_screenshots": [
                {
                    "image_url": "https://temporary.com/image.jpg",
                    "alt_text": "Description of image above"
                },
                {
                    "image_url": "https://temporary.com/image2.jpg",
                    "alt_text": "Description of image above"
                }
            ]
        }
    },
    "app_plans": [
        {
            "plan_uuid": "332653a3-df51-45ce-a873-fbb0b1ccb49f",
            "is_free": false,
            "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",
            "is_free": false,
            "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"
                    ]
                }
            }
        }
    ]
}

For full details on the App manifest, see App Manifest.

3. Update your App Manifest

Use an API call to update your app manifest with the relevant information pointing to your development environment.

Key

Description

installation_endpoint

Installation callbacks will be sent here each time a user installs your App

uninstallation_endpoint

Uninstallation callbacks will be sent here each time a user uninstalls your App

updowngrade_installation_endpoint

Upgrade and downgrade events will be sent here each time a user upgrades your app

base_sso_url

The login entry point users will be sent to when SSOing into your product. This will be opened in an iframe in the Duda editor.

For this tutorial, you can use these endpoints:

  1. Set the endpoints to a webhook testing tool which always returns a 200 HTTP status code and makes sure you can access its details. There are many free tools online such as beeceptor.com or http://webhook.site/ which can receive callbacks or webhooks from Duda.
  2. Set SSO base path to a URL that can be open inside of an iframe, such as: https://www.w3schools.com (or a URL on your site).
curl -X POST https://api-sandbox.duda.co/api/integrationhub/application/{{appUuid}} -u 'AppAccountUser:AppAccountPass' -H 'Content-Type: application/json' -d '{{YOUR UPDATED MANIFEST JSON}}'

📘

API Behavior

  1. Sending a POST update that changes immutable parameters (such as UUID) will return a 400 error.
  2. Each manifest update via a REST API should include a complete manifest with all fields. Sending a partial manifest is not supported and will result in unexpected behavior.

🚧

URL Policies

  1. All URLs must be HTTPS.
  2. In order to comply with Duda’s White Label policy, paths should not include the string ‘Duda’. You can use 'website builder' instead.

4. Create a site and install your app

  1. Log in to Duda's UI on the Sandbox Environment.
  2. Click 'Create a responsive site'
  3. Select a template and name your site. A new site will be created. Get the Site Name from the URL Bar:
How to find Site Name in the Duda editorHow to find Site Name in the Duda editor

How to find Site Name in the Duda editor

To install your app on the site:

  1. Click 'App Store' on the left panel
  2. Find your app and click 'Add'
  3. Select a plan

📘

Don't see your app or you plans?

The app store displays only apps and plans with valid profiles for the app and plans.
If you don't see your app or one of your plans, fix the profile in the manifest.

Duda will send an installation callback to your installation endpoint of the following format:

{
    "auth": {
        "type": "bearer",
        "authorization_code": "XXX-XXXXX-XXXXX",
        "refresh_token": "YYY-YYYYY-YYYYY",
        "expiration_date": 1554254560438
    },
    "api_endpoint": "https://api-sandbox.duda.co/",
    "installer_account_uuid": "10",
    "account_owner_uuid": "12",
    "user_lang": "en",
    "app_plan_uuid": "332653a3-df51-45ce-a873-fbb0b1ccb49f",
    "recurrency": "MONTHLY",
    "site_name": "1501ccca016a4220861ef07fe2c8eb0d",
    "free": true
}

The app_plan_uuid is the plan the user selected to install. The recurrency is the payment recurrency (ANNUAL, MONTHLY, or NULL for free plans). The site_name is the identifier for the site on which the app was installed. It should be the same value as shown in the browser address bar.

📘

Site names

Site names are global UUIDs for all Duda environments. Site names are used for most of the interactions of your App with the App Store. You should store site names and use them as the main identifier of installations.

The properties installer_account_uuid, account_owner_uuid, and user_lang are explained on Hierarchy of users (need to write this page). The properties under auth are explained on App Store: Getting Started Guide, additional in-dept explanation is found on Authentication: Apps .

If the endpoint on installation_endpoint returned HTTP status code 200, Duda will finish the installation and direct the user to an iframe with the source specified on base_sso_url.

📘

The 'Free' flag

Duda will send the free flag for installation which won't be paid. These would include:

  1. Installations on test environments, such as the Sandbox environment you will be working on in throughout this guide.
  2. Installations generated by Duda employees for demo, sales, QA and support cases.

5. Use REST APIs to get site data

Once Duda starts the installation process, your app can use REST APIs to get data about the site and perform other actions. You can use API calls during the installation phase before you return Duda an HTTP response for the installation callback. Duda will present the user with the progress bar until you return an HTTP response.
The APIs your App can use restricted by the scopes property of your app manifest. See further details on available scopes.

📘

Bearer authentication

All site APIs require token authentication in addition to the Account Basic Authentication.
Use the X-DUDA-ACCESS-TOKEN header to send the token.

Getting account branding

Use the following call to get the branding of the reseller (need to write this page). This API is available for all apps. Replace the XXX-XXXXX-XXXXX is the token you got in the installation callback under authorization_code:

curl -X GET https://api-sandbox.duda.co/api/integrationhub/application/site/{{site name}}/branding -u 'AppAccountUser:AppAccountPass' -H 'X-DUDA-ACCESS-TOKEN: Bearer XXX-XXXXX-XXXXX' -H 'Content-Type: application/json'

You should expect a response of the following format:

{
    "logo": "https://irt-cdn.multiscreensite.com/-resellers-preview/someaccount/logo/2rs7j2mr00to947a6625c6uc1m.png",
    "color": {
        "links": "#8c8c8c",
        "button_background": "#e218c6",
        "button_text": "#fdb33e",
        "text_on_light": "#fdb33e",
        "text_on_dark": "#fdb33e",
        "header_background": "#2c3e50",
        "preview_background": "#d4e4f5"
    },
    "preview_background_image": "none",
    "dashboard_domain": "http://someaccount.editor-sandbox.multiscreensite.com"
}

📘

APIs domain

The above example uses the api-sandbox.duda.co domain, which is taken from the installation callback payload specified above.
You should set the host of all site-related API calls programmatically based on the api_endpoint property sent to you on the installation callback.

Getting the reseller details

Use the following call to get the reseller details (app scope GET_ACCOUNT_DETAILS is required):

curl -X GET https://api-sandbox.duda.co/api/integrationhub/application/site/{{site name}}/account/details -u 'AppAccountUser:AppAccountPass' -H 'X-DUDA-ACCESS-TOKEN: Bearer XXX-XXXXX-XXXXX' -H 'Content-Type: application/json'

You should expect a response of the following format:

{
    "uuid": "10",
    "first_name": "name",
    "last_name": "name",
    "email": "[email protected]"
}

Getting Content Library for the site

Use the following call to get the site's Content Library:

curl -X GET https://api-sandbox.duda.co/api/integrationhub/application/site/{{site name}}/content -u 'AppAccountUser:AppAccountPass' -H 'X-DUDA-ACCESS-TOKEN: Bearer XXX-XXXXX-XXXXX' -H 'Content-Type: application/json'

For a full reference of the content library data structure, see Duda's API documentation.

🚧

Validity of Content Library data

The Content Library is a repository used by web pros for storing assets which they use during the site-building process.
The data in the Content Library is not verified. In particular, emails, phone numbers, and addresses are not verified.

Refreshing the access token

Every 12 hours the authentication token is invalidated. To receive the new token you need to send the following request with the refresh token you received when installing the app:

curl -X POST https://api-sandbox.duda.co/api/integrationhub/application/{{appUuid}}/token/refresh -H 'Content-Type: application/json' -d '{"refreshToken": "YYY-YYYYY-YYYYY"}'

You should expect a response in the following format:

{
    "type": "bearer",
    "authorization_code": "XXX-XXXXX-XXXXX",
    "refresh_token": "YYY-YYYYY-YYYYY",
    "expiration_date": 1555550616864
}

For further reading on Authentication & Token Management

📘

Complete REST API documentation

For all available APIs, see the complete [REST API documentation] for the app store.

6. Upgrade your app

To upgrade your app plan, open the app store and click on upgrade on your app card.
Select the new plan you which to upgrade to.
Duda will send a callback event with a payload of the following format to the endpoint registered under updowngrade_installation_endpoint in your manifest:

{
    "app_plan_uuid": "332653a3-df51-45ce-a873-fbb0b1ccb49f",
    "recurrency": "MONTHLY",
    "site_name": "1501ccca016a4220861ef07fe2c8eb0d"
}

Once received, you should do the necessary action to update your app behavior to the new feature plan. The Duda UI will wait until the app responds to the callback in order to finish the upgrade process.

7. Uninstalling your app

To uninstall your app, open the app store, click on Options and info on your app card, then click remove and follow the instructions.
Duda will send a callback event with a payload of the following format to the endpoint registered under uninstallation_endpoint in your manifest:

{"site_name":"1501ccca016a4220861ef07fe2c8eb0d","free":false}

Once received, you should do the necessary action to acknowledge the uninstall. The Duda UI will wait until the app responds to the callback in order to finish the upgrade process.

🚧

Data and configuration retention

Duda expects apps to retain data and configuration of each removed installation for 60 days. During this period, if the app is installed again the data and configuration should be recovered.

8. Handle SSO links from Duda

To generate an SSO link for your app, open your app from the app store.
Duda will render an iframe to the URL specified in the manifest under base_sso_url.
The URL will be of the following format:

https://app.domain.com/websitebuilder?site_name={{site name}}&timestamp={{time stamp}}&lang={{use langauge code}}&is_white_label={{true/false}}&iframeSDKSrc={{SDK URL}}&current_user_uuid={{user uuid}}&secure_sig=SIGNATURE

The link will be signed with the Duda’s private key, and can be verified with the public key listed in the manifest.

Implementation details:

  1. The signed string if of the format: siteName + ':' + sdk_url + ':' + timestamp
  2. The SSO signature is encoded in Base64.
  3. The SSO URI is encoded using RFC3986.

For further reading see Authentication: SSO Links


Did this page help you?