The following document provides guidance on specific points within DIY website creation and maintenance flows. For general documentation visit our development portal at https://developer.duda.co. A general overview of implementing a DIY site creation flow can be found at https://developer.duda.co/docs/diy-onboarding

Built-in Duda template chooser

Display the template chooser

The first step your customers will take on the DIY website creation flow is to choose a template as the basis of their new site. Duda provides a ready-to-use, white-labeled template chooser complete with convenient filtering options. For some partners, the Duda UI will suffice. However, if you need to build a custom view within your own system, we provide API endpoints to assist you in this task.

Example white-labeled template chooser.

Create a template chooser (optional)

The first step your customers will take on the DIY website creation flow is to choose a template as the basis of their new site. Duda provides API endpoints to assist in the creation of your own template chooser.


Your product can make a call to the template details API endpoint to get meta data surrounding the team templates, this will include screenshots and a preview URL to give users an idea of the design of a template before choosing.

Getting Template Data

A list of team template ids will need to be stored within your product to make the individual calls to get template details. The response to these calls can be cached, as the data is unlikely to change and the network overhead can grow when expanding beyond a handful of templates.


Documentation

Get All Templates API Call

Get Template Info API Call

Request Example

curl --request GET \

 --url https://api.duda.co/api/sites/multiscreen/templates/{template_id} \

 --header 'authorization: Basic YXNkZmFkZjphc2RmYXNkZmFk'

Response Example

{

  template_name": "Auto Repair",

  preview_url": "http://dashboard.multiscreensite.com/preview/dm-theme-1005442-en-328",

  thumbnail_url": "https://irp-cdn.multiscreensite.com/0f8a8/repair_BigPreview.png",

  desktop_thumbnail_url": "https://irp-cdn.multiscreensite.com/0f8a8/repair_desktop.png",

  "tablet_thumbnail_url": "https://irp-cdn.multiscreensite.com/0f8a8/repair_ipad.png",

  "mobile_thumbnail_url": "https://irp-cdn.multiscreensite.com/0f8a8/repair-mobile.png",

  "template_id": 1005442,

  "template_properties": {

    "can_build_from_url": false,

    "has_store": false,

    "has_blog": false,

    "page_count": 5

  }

}

The response to this call can be cached within the your system, as the data is unlikely to change often. If you choose to simply fetch data for all existing Duda templates, you can use the get all templates endpoint, instead of making an individual call per template.New Paragraph

Provisioning a site based on template selection

An entire site object can be used in the body of the POST request, but only the templateId is required. Additionally, a default_domain_prefix property can be sent to configure the default sub-domain that will be used when the site is published


Documentation

Create Site API Call

Get Template Info API Call

Request Example

curl --request POST \ --url https://api.duda.co/api/sites/multiscreen/create \
--header 'authorization: Basic YmEyYTasdiJNDpPUDZwVGc=' \
--header 'content-type: application/json' \
--data '{"template_id":"1000772", "default_domain_prefix": "subdomain"}'

Response Example

{

  "site_name":"28e1182c"

}

The site_name is unique across Duda and should be saved with the user record in your system.

Specifying a site name


The API create request does not allow specified site names, as shown in the create site response a random name will be returned from a successful POST call. You can store this randomly generated name along with a user-specified site name in your own system or we provide an    external_uid     property that may be used when creating or updating a site.

SSO into the site editor (Account creation and permissions)


After provisioning a site, a new user must be created and granted the correction permissions to edit the site. Once a user has been given access, a call can be made to generate a secure link. When followed, the link will allow the user to authorize into the Duda editor without entering new credentials. In effect, the user shouldn't notice they are leaving your internal system.

Create a new user

Use the selected UID from the create user API call and the site_name found in the response of the create site API call to grant permission to edit the new site.


Documentation

Create User Call

Request Example

curl --request POST \ --url https://api.duda.co/api/accounts/create \

--header 'authorization: Basic YmEyYTBjNWNkNDpPUDZwVGc=' \

--header 'content-type: application/json' \

--data '{"account_type":"CUSTOMER","account_name":"1234566789"}'

The account_name property should match a UID found within your internal systems to identify a particular user. This way your system is the source-of-truth for user identification, and subsequent calls using the identifier (such as single-sign-on), will continue to work after the current session.

While not required, Duda recommends sending an email property in the API request payload as well. If this is provided the user can receive stats or site comment emails to their account.

Granting user access to the site

Use the selected UID from the create user API call and the site_name found in the response of the create site API call to grant permission to edit the new site.


Documentation

Grant Site Access

Request Example

curl --request POST \ --url https://api.duda.co/api/accounts/{account_name}/sites/{site_name}/permissions \ --header 'authorization: Basic YmEyYTBjNWNkNDpPUDZwVGc=' \ --header 'content-type: application/json' \ --data '{"permissions":["PUSH_NOTIFICATIONS","REPUBLISH","EDIT","INSITE","PUBLISH","CUSTOM_DOMAIN","RESET","SEO","STATS_TAB","BLOG"]}'

Signing the user into the editor

Once the user has been granted access, a new secure link can be retrieved. Redirect the user to the specified link to allow access to the editor without having to use any new credentials.


Documentation

Grant Site Access

Request Example

curl --request GET \

--url https://api.duda.co/api/accounts/sso/{account_name}/link?site_name={site_name}&target=EDITOR' \

--header 'authorization: Basic YmEyYTBjNWNkNDpPUDZwVGc='

The link that is returned from this call is only valid for two minutes, because of the limited time frame, it is recommended you do not make this API call when rendering the page. Instead, the link should be generated at the time the user intends to enter the editor.

Assigning a domain to the site (and publishing)


Duda can configure the editor's 'publish' button to redirect back to your system on first publish. This allows you to implement your own custom flow for domain registration. If domain registration happens outside of Duda, your system must make API calls to update the site with the new domain, and also make a call to publish the site live. Duda can provide the necessary DNS setting needed for domains during your implementation.

Update site with new domain name

Using the site_name, you can update the domain name of the site.  Publishing the site will reflect this new domain name change.


Documentation

Update Site

Publish Site

Request Example

curl --request POST \
 --url https://api.duda.co/api/sites/multiscreen/update/{site_name} \
 --header 'authorization: Basic YmEyYdafjenDDpPUDZwVGc=' \
 --header 'content-type: application/json' \
 --data '{"site_domain": "mynewdomain.com"}

If a user decides on using the default domain and a chosen subdomain e.g., mydudasite.mygenericsitesdomain.com, it's possible the domain may already be in use by another site. In this case you will receive a "ResourceAlreadyExists" error code and will have to retry with a different subdomain.

curl --request POST \
 --url https://api.duda.co/api/sites/multiscreen/publish/{site_name} \
 --header 'authorization: Basic YmEyYTBjNWNkNDpPUDZwVGc='

Upgrading and Downgrading Plans

Duda allows the use a set of custom plans. A Plan is defined at the site level and controls which features are available for the users in a specific site. For example, a plan might define that Hide-per-device is available, but eCommerce is not available.


A site, by default, will have a plan associated with it, and users can be presented with upgrade or downgrade option to change the plan. Duda will work with you to configure the features of your plans, and provide plan ids during the integration process.

Setting Plans (API)

You can set or change the plan of a site utilizing the site_name and plan_id obtained from the list site plans API call.


Documentation

List Site Plans

Update Site Plan

Request Example

curl --request POST \
 --url https://api.duda.co/api/sites/multiscreen/{site_name}/plan/{plan_id} \
 --header 'authorization: Basic 123xyz'

Setting Plans (Editor)

Duda can provide ways to initiate an upgrade flow from within the editor. In the case a user clicks on a feature which is not available in the current plan, a lock is presented with a custom upgrade message. Once clicked, an upgrade flow can be activated. The user is redirected to an external page in which the upgrade flow can be managed by your system.

Permissions vs. Plans


Both Permissions and Plans control the level of accessibility in the editor, however there are a few major differences between the two.

  • A missing permission will hide the feature while a missing feature in a plan will present an upgrade flow.
  • Permissions are managed at the user level while plans are managed at the site level.
  • Plans granularity is much deeper than permissions (plans can control the accessibility of distinct widget, permissions cannot).


Pushing data to newly created sites

Newly provisioned sites can be created already populated with the content of the customer, resulting in what Duda has coined as instant websites. Content from your platform can be pushed to the site's content library immediately after creation. The following pieces of content were identified as candidates for connected data:


  • Phone Number
  • Logo
  • Email
  • Business Name
  • Hours
  • Locations
  • Social Links


Documentation

Content Object

Update Content Library

Request Example

curl --request POST \
 --url https://api.duda.co/api/sites/multiscreen/{site_name}/content \
 --header 'authorization: Basic 123xyz'
 --header 'content-type: application/json' \
 --data '...'

Example Data Payload

{
   "location_data": {
       "phones": [
           {
               "phoneNumber": "123-123-1234",
               "label": "Main Phone"
           },
           {
               "phoneNumber": "18001234567",
               "label": "Fax"
           }
       ],
       "emails": [
           {
               "emailAddress": "help@example.org",
               "label": "General Help Email"
           },
           {
               "emailAddress": "billing@example.org",
               "label": "Billing Questions"
           }
       ],
       "label": "Example Service Business",
       "social_accounts": {
           "facebook": "service",
           "linkedin": "service",
           "instagram": "service",
           "twitter": "service",
       },
       "address": {
           "streetAddress": "577 College Ave",
           "postalCode": "94306",
           "region":"CA",
           "city": "Palo Alto",
           "country": "US"
       },
       "address_geolocation": "1833 Harvard St NW, Washington, DC 20009, USA",
       "geo": {
           "longitude": "-122.4757527166",
           "latitude": "37.502439189002"
       },
       "logo_url": "https:/cdn.multiscreensite.com/path/to/logo.svg",
       "business_hours": [
           {
               "days": [
                   "SAT",
                   "SUN"
               ],
               "open": "00:00",
               "close": "00:00"
           },
           {
               "days": [
                   "MON",
                   "TUE",
                   "WED",
                   "THU",
                   "FRI"
               ],
               "open": "09:00",
               "close": "18:00"
           }
       ]
   },
   "additional_locations": [
       {
           "uuid": "276169839",
           "phones": [
               {
                   "phoneNumber": "123-123-1234",
                   "label": ""
               }
           ],
           "emails": [],
           "label": "2nd Location",
           "social_accounts": {},
           "address": {},
           "geo": {
               "longitude": "34.78337",
               "latitude": "32.07605"
           },
           "logo_url": null,
           "business_hours": null
       }
   ]
}

When pushing photos to Duda we recommend uploading each image to our CDN first. This can be done with our uploads API endpoint.

Updating Content

When data changes within your platform. The same API call should be made to keep the data on the website in sync. Content library are stored in an unpublished state after updating. A separate publish content API request for the data to appear on the live site.


Documentation

Update Content Library

Publish Content Library

Request Example

curl --request POST \
 --url https://api.duda.co/api/sites/multiscreen/{site_name}/content/publish
 --header 'authorization: Basic 123xyz'

Cancelling accounts

When an account cancels some site cleanup processes are required. Duda should receive a request, at the very least, to unpublish the account's site. This prevents Duda from charging for the site. Additionally, if the action is permanent (like an account deletion), an API request should be sent to delete the Duda site and account as well.


Documentation

Unpublish Site

Delete Account

Delete Site

Collecting lead form submissions


With webhooks you can subscribe to all form submissions from your user's sites. The form submission webhook provides all the data from the form, the timestamp of the submissions as well as the site it was performed on. You can provide the URL that will receive the webhook's payload during implementation, after which any form submitted by a site under your Duda account will trigger an event to that URL. The site owners will also receive the data via email, and be able to review form submissions from within the editor itself.


Configuration


The following table highlights some properties that can be set by both Duda and your organization to customize the DIY experience. You can begin gathering values for these properties to aid in your implementation. Note that not all properties may necessarily be needed for your particular flow.


Account Customizations

Property Name Value Type Description
dashboard.url custom Product Property URL to which the user will be redirected when clicking the 'home' icon in the Duda editor
D1.publish.button.action REDIRECT Product Property Behavior when the user clicks the publish button in the Duda editor
D1.publish.button.url custom Product Property URL to which the user will be redirected when clicking the publish button
customers.block.dashboard true Product Property Disallows users to access the Duda dashboard, preferring to send users to your internal system instead
dashboard.hasAccountSettings false Product Property Disallows users from changing their account name from within Duda, keeping you as the source-of-record for user accounts