App Personalization

Getting started with App Personalization service APIs

August 25, 2023

Contributed by:

The Getting started with App Personalization service APIs section provides information on prerequisites to use the App Personalization APIs, sample request and response, and how to personalize apps for supported Citrix Workspace app clients.

Prerequisites to make requests from a client to App Personalization APIs

To use App Personalization service APIs, you must specify the following parameters in each API request:

Citrix Customer ID: Citrix-CustomerId in a request header.
CCAuth Token: Secure HTTP requests sent to Citrix Cloud by using a custom Authorization header that contains a Citrix Cloud bearer token. Bearer tokens are required for actions that occur on behalf of a user.

For information on how to obtain the Citrix-CustomerId and generate a custom Authorization header that contains the bearer token, see the Get started with Citrix Cloud APIs section.

Request and response in the App Personalization service APIs

The following is an example of a request and response:

POST https://personalization.cloud.com/personalizations

Request header

Accept: application/json
Content-Type: application/json
Citrix-CustomerId: 
Authorization: CWSAuth Bearer=
<!--NeedCopy-->

Request body

{
    "appName": "CitrixWorkspace",
    "platform": "Windows" or "Mac" or "Android" or "iOS",
    "product": "Citrix Workspace app",
    "abmDetails": "{"abmId": ["example@citrix.com"], "orgDetails": [{"orgId": "123456", "orgName": "example"}]}"(**required only for iOS),
    "helpURL": "www.helpurl.com"(**required only for Windows),
    "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
    "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="(**required only for Citrix Workspace app),
    "storeURL": "https://testserver.net/Citrix/MyStore/discovery"(**required only for Citrix Workspace app),
    "macMenuBarIconOnlineDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="(**required only for Mac),
    "macMenuBarIconOfflineDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="(**required only for Mac),
    "viewerIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="(**required only for Mac)
}
<!--NeedCopy-->

Parameters

appName. Specify the name of the app.
platform. Specify the platform of the app. Supported platforms: “Android,” “iOS,” “macOS,” and “Windows.”
product. Specify the name of the app to be renamed. Supported apps: “Secure Mail,” “Secure Web,” “Citrix Files,” and “Citrix Workspace app.”
appIconDataURI. Specify a base-64 encoded icon URI for the app you want to brand.
secondaryDataURI. Specify a base-64 encoded icon URI for the app you want to brand.
abmDetails. Specify the Apple Business Manager Email ID & Organisation details. This parameter is applicable only to iOS.
helpURL. Specify the help URL. This parameter is applicable only to Windows.
storeURL. This is an optional parameter. Specify the store URL to be configured in the Citrix Workspace app. This parameter is applicable only for Citrix Workspace app across all the 4 platforms.
viewerIconDataURI. Specify a base-64 encoded icon URI to replace the existing Citrix Viewer icon. This parameter is applicable only to Mac.
macMenuBarIconOnlineDataURI. Specify a base-64 encoded icon URI to replace the existing Citrix Menubar Online icon. This parameter is applicable only to Mac.
macMenuBarIconOfflineDataURI. Specify a base-64 encoded icon URI to replace the existing Citrix Menubar Offline icon. This parameter is applicable only to Mac.

Response -201 Created

{

"type": "Success",
"detail": "Customer request for branding app is completed successfully",
"parameters":
[
    {
        "name": "id",
        "value": "1572cd92447742ef81638594a91f6b86"
    }
]

}
<!--NeedCopy-->

Personalize Citrix Workspace app for Windows

To personalize Windows apps, do the following:

In the Citrix Developer portal, go to Platform > App Personalization Service REST API > API Exploration > Personalizations > PersonalizationsPost > INVOKE API.
Submit a POST/ Personalizations request that contains the following parameters:
- appName
- platform
- product
- appIconDataURI
- secondaryIconDataURI
- helpURL
- storeURL
It can take 2–4 working days for the app to be personalized on Apple’s App Store (preview).
Store URL parameter is optional as mentioned in the Troubleshooting page.
Help URL parameter is optional as mentioned in the Troubleshooting page.
After making the request, use the GET/ Personalizations/{id} API to verify that the request was created successfully.
Retrieve the versions available to rebrand using the PersonalizationVersionGet API call.
Submit the POST/ Personalizations/{id}/builds?async=true API with the version parameter to create the personalized app.
After the build request completes, it can take a few minutes for the status of the build to update.
Use the GET/ Personalizations/{id}/builds/{id} request to fetch the resultLocation information and download the personalized app (.exe file) from the completed build.

Example payload

            {
                "appName": "Workspace",
                "platform": "Windows",
                "product": "Citrix Workspace app",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery",
                "helpURL": "www.helpurl.com"
            }
<!--NeedCopy-->

Personalize Citrix Workspace app for Mac

To personalize macOS apps, do the following:

In the Citrix Developer portal, go to Platform > App Personalization Service REST API > API Exploration > Personalizations > PersonalizationsPost > INVOKE API.
Submit a POST/ Personalizations request that contains the following mandatory parameters:
- appName
- platform
- product
- appIconDataURI
- secondaryIconDataURI
- storeURL
- viewerIconDataURI
- macMenuBarIconOnlineDataURI
- macMenuBarIconOfflineDataURI
Store URL parameter is optional as mentioned in the Troubleshooting page.
Viewer Icon and Mac Menubar Online and Offline icons are optional as mentioned in the Troubleshooting page.
Add the optional Viewer Icon and Mac Menubar Online and Offline icons to personalize them.
After making the request, use the GET/ Personalizations/{id} API to verify that the request was created successfully.
Retrieve the versions available to rebrand using the PersonalizationVersionGet API call.
Submit the POST/ Personalizations/{id}/builds?async=true API with the version parameter to create the personalized app.
After the build request completes, it can take a few minutes for the status of the build to update.
Use the GET/ Personalizations/{id}/builds/{id} request to fetch the resultLocation information and download the personalized app (.dmg) from the completed build.

Example payload

            {
                "appName": "Workspace",
                "platform": "Mac",
                "product": "Citrix Workspace app",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery",
                "macMenuBarIconOnlineDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "macMenuBarIconOfflineDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "viewerIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="
            }
<!--NeedCopy-->

Personalize Citrix Workspace app for Android

To personalize Android apps, do the following:

In the Citrix Developer portal, go to Platform > App Personalization Service REST API > API Exploration > Personalizations > PersonalizationsPost > INVOKE API.
Submit a POST/ Personalizations request that contains the following mandatory parameters:
- appName
- platform
- product
- appIconDataURI
- secondaryDataURI
- storeURL
It can take 2–4 working days for the app to be personalized on Google Play (preview).
Store URL parameter is optional as mentioned in the Troubleshooting page.
After making the request, use the GET/ Personalizations/{id} API to verify that the request was created successfully.
Citrix creates an app onboarding request. This request generates a bundle ID for you.
Citrix creates App pages for Google Play Store. It includes the wait time for the app to be approved by Google for their store. It can take 2–4 working days for the app to be personalized on Google Play (preview).
Apps are made available for open testing (through beta channel) to you and a new release is made available as and when the respective apps are generally available.
Use the GET/ Personalizations/{id}/builds/{id} request to fetch the resultLocation information and download the personalized app (.mdx file) from the completed build. This is applicable for Secure mail, Secure web and Citrix files apps.
Test the app and then promote it to your production environment by using the POST/ Personalizations/{id}/$promote API.

Example payload

            {
                "appName": "Workspace",
                "platform": "Android",
                "product": "Citrix Workspace app",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery"
            }
<!--NeedCopy-->

Personalize Citrix Workspace app for iOS

To personalize iOS apps, do the following:

In the Citrix Developer portal, go to Platform > App Personalization Service REST API > API Exploration > Personalizations > PersonalizationsPost > INVOKE API.
Submit a POST/ Personalizations request that contains the following parameters:
- appName
- platform
- product
- appIconDataURI
- abmDetails
- secondaryDataURI
- storeURL
Store URL parameter is optional as mentioned in the Troubleshooting page.
After making the request, use the GET/ Personalizations/{id} API to verify that the request was created successfully.
Citrix creates an app onboarding request. This request generates a bundle ID for you.
Citrix creates App pages for App Store. It includes the wait time for the app to be approved by Apple for their store. It can take 2–4 working days for the app to be personalized on Apple’s App Store (preview).
Apps are made available for open testing (through TestFlight) to you and a new release is made available as and when the respective apps are generally available.
Use the GET/ Personalizations/{id}/builds/{id} request to fetch the resultLocation information and download the personalized app (.mdx file) from the completed build.This is applicable for Secure mail, Secure web and Citrix files apps.
Test the app and then promote it to your production environment by using the POST/ Personalizations/{id}/$promote API.

Example payload

            {
                "appName": "Workspace",
                "platform": "iOS",
                "product": "Citrix Workspace app",
                "abmDetails": "{"abmId": ["example@citrix.com"], "orgDetails": [{"orgId": "123456", "orgName": "example"}]}(**required only for iOS)",
                "appIconDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "secondaryDataURI": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII=",
                "storeURL": "https://testserver.net/Citrix/MyStore/discovery"
            }
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

App Personalization OpenAPI Specification

Copy Download

Getting started with App Personalization service APIs

August 25, 2023

Contributed by:

August 25, 2023

Contributed by:

Prerequisites to make requests from a client to App Personalization APIs
Request and response in the App Personalization service APIs
Personalize Citrix Workspace app for Windows
Personalize Citrix Workspace app for Mac
Personalize Citrix Workspace app for Android
Personalize Citrix Workspace app for iOS

Was this helpful

Resources

App Personalization OpenAPI Specification

Copy Download

Getting started with App Personalization service APIs

Prerequisites to make requests from a client to App Personalization APIs

Request and response in the App Personalization service APIs

Personalize Citrix Workspace app for Windows

Personalize Citrix Workspace app for Mac

Personalize Citrix Workspace app for Android

Personalize Citrix Workspace app for iOS

Resources

App Personalization OpenAPI Specification

In this article

Resources

App Personalization OpenAPI Specification