Configure and Install a custom marketplace app

Provision a deployed custom app

In order to register your app with XM Cloud you either deploy your app to a hosting provider first or run it locally (for testing and development purposes). If you want to only run it locally refer to the next chapter.

Deploy your app to a hosting provider

Pre-Requisites:

• Ideally you have your code available in a source code repository like GitHub.
• You have an account with a hosting provider like Vercel, Netlify, Azure etc.

Build and Deploy in Vercel

1. Create a new Project

In Vercel, hit the Add new Button and create a new Project.

2. Import your Marketplace app repository

Find the app you want to connect with your project. New repos are listed on top. You can also search in your different connected repositories.

3. Select the root directory and deploy

The root directory is marked with a Next.js logo. This will also set the Framework preset. There is no need for Build and Output Settings changes or Environment Variables at this point.

4. Deployment successful

Register app in Cloud Portal

1. Enter Developer Studio in Cloud Portal

Accept Terms of use if not yet done

2. Create app

3. Set name and select app type

Currently only Custom Apps are available. Public apps will be coming soon.

4. Your app is created

5. Configure app

In the app configuration you can set everything to connect to the right route within the app, set what extension points this app is meant to show in and set an app image. As this app already provides examples for all extension points we could configure all of them.

5.1 Select Extension Point and Route URL

I selected the Standalone extension point for now. This will show the app directly in the Cloud portal. Of course this needs to be selected based on your requirements.

Additionally, I set the route to /standalone-extension as the page, our marketplace app is referring to is located in that route.

You can also define a display name if you want to configure the same app with different URLs etc to connect your local running app (see “Local” chapter).

As this app provides all extension point examples you can also configure the other options.

Please Note: When using the extension point Custom Field you also need to add the custom field to the content template (Content Model) as type "Marketplace Type -> Plugin".

Read more in the Sitecore documentation

5.2 API access

Configuring the API access let's you govern what Sitecore APIs or API groups the app is allowed to access. Currently you can only grant access to "XM Cloud APIs" which include access to:

• Authoring and Management GraphQL API
• XM Cloud Sites REST API
• XM Cloud Pages REST API
• Experience Edge Token REST API
• Experience Edge Admin REST API

The Marketplace starter kit does not require that access as all data retrieved comes from the application context (through client package). If you require XM Cloud specific data, e.g. item access, this would need the activation of the API access.

Read more in the Sitecore documentation

5.3 Set Deployment URL

You need to set the URL where your app is hosted. You find the deployment URL with your hosted project in Vercel.

Additionally, you should set the App Logo URL, ideally provided from your apps /public folder.

Afterwards you activate the app (top right corner).

6. Install the App

Now the app is visible in the “My apps” section in the “TO BE INSTALLED” status. Hit the “Install” button.

After the installation the app will be available to all Organisation Users.

7. Testing the app

As I chose the extension point “Standalone” the app is available in the Cloud Portal as expected using the app logo I configured.

Once you click it, it will open in a separate window, this time showing also the appContext.name and appContext.id as it is now registered and running in the context of Cloud Portal and XM Cloud.

Now you can start building the logic for your app. Find the documentation here: https://doc.sitecore.com/mp/en/developers/marketplace/register-a-custom-app.html

Register Local running app

Running the local app in the context of Cloud Portal XM Cloud is working the same way as setting up your deployed app. This way, all authentication and other connection related configuration is handled by Sitecore.

You do not need to deploy the app to a hosting provider as you plan run the app on localhost.

Find the steps below. For more details to description above.

1. Enter Developer Studio
2. Create App
3. Set name of the app (e.g. “My Marketplace App (Local)”) and select type “Custom App”
4. Your App is created
5. Configure App
   • Select the extension point e.g.“Standalone”
   • Set Route to “/standalone-extension”
   • Set Deployment URL: http://localhost:3000
   • Set App Logo URL e.g. https://placehold.co/512x512.png
6. Install the App
7. Test the App (Make sure you have started your app. npm run dev)

Ideally you only connect your local running apps on non-productive environments.

Resources

Read more