Media Shuttle Platform API Integration Guide

Integrating an application with the Media Shuttle Platform API allows you to control the lifecycle of a portal, including creation, customization, and deployment.

Creating a Portal

Using a valid access token, create a new portal via the /v1/mediaShuttle/portals endpoint and specify portal security settings related to link authentication, trusted referring sites, and additional portal security settings.

For more information about portal security, see the Signiant Help Center.

To create a new portal:

Create a new JSON file specifying the new portal details, including the relevant configuration options for the portal type:

{
  "name": "New Portal",
  "url": "new-portal.mediashuttle.com",
  "type": "Share",
  "expiresOn": "2033-01-01T01:01:01.000Z",
  "authentication": {
    "configurations": [
      {
        "type": "MEDIA_SHUTTLE"
      }
    ]
  },
  "linkAuthentication": {
    "enableUnauthenticatedUploads": true,
    "enableUnauthenticatedDownloads": true
  },
  "trustedReferrersForEmbeddingPortalUrls": ["example.com"],
  "requireAuthentication": true,
  "enableRecipientPicking": true,
  "portalMembersMustUseClientSoftware": false
}

Note: The above example creates a Share Portal. For examples of additional portal types and configuration options, see the API documentation.

Save the file as newPortal.json.
In your terminal or command prompt, navigate to the directory where newPortal.json is stored.
Use the curl utility to POST to the v1/mediaShuttle/portals endpoint, including an access token in the header and newPortal.json as the request body:

curl -X POST https://platform-api-service.services.cloud.signiant.com/v1/mediaShuttle/portals \
 -H "accept: application/json" \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 --data @newPortal.json

The response body contains the portal details, including the portalId, url, and additional configuration details:

{
  "name": "New Portal",
  "url": "new-portal.mediashuttle.com",
  "type": "Share",
  "createdOn": "2022-09-21T17:29:52.509+0000",
  "lastModifiedOn": "2022-09-21T17:29:52.509+0000",
  "portalMembersMustUseClientSoftware": false,
  "expiresOn": "2033-01-01T01:01:01.000Z",
  "requireAuthentication": true,
  "trustedReferrersForEmbeddingPortalUrls": ["example.com"],
  "authentication": {
    "configurations": [
      {
        "type": "MEDIA_SHUTTLE"
      }
    ]
  },
  "linkAuthentication": {
    "enableUnauthenticatedUploads": true,
    "enableUnauthenticatedDownloads": true
  },
  "enableRecipientPicking": true,
  "portalId": "abc12345-2222-4b09-afac-9391bc097614",
  "accountId": "cba54321-2222-42f8-9f35-907934f744b2",
  "serviceId": "a1b2c3d4-2222-4cf4-913b-897d821ef7f0"
}

Note: Portal storage must be configured via the Media Shuttle IT Administration Console.

Setting Portal Branding

Media Shuttle portal branding is configured using the,/v1/mediaShuttle/{portalId}/branding API endpoint, which controls the look and feel of a portal. In addition to setting the color scheme and panel position using the interface panel properties, you can upload assets to Signiant-provided cloud storage to use as background images, logos, and favicons.

For general information about portal customization, see the Signiant Help Center.

Once a portal is customized using the API, you must continue using the API to apply branding changes to the portal. Changes made in the Operations Administration Console after customizing the portal via the APIcan result in inconsistent behavior.

Interface Panel Properties

The interface panel properties control the color scheme of a portal and the interface panel position within a browser window.

All values must be included as strings.

Property	Description	Example Value
`color`	RGBA value setting the portal interface panel and transparency	`rgba(78,23,126,0.9)`
`fontColor`	RGB value setting the portal maximize, refresh, and other icons	`rgb(255,255,255)`
`borderColor`	RGB value setting the portal interface panel border color	`rgb(78,23,126)`
`buttonColor`	RGB value setting the portal button color	`rgb(55,5,57)`
`buttonFontColor`	RGB value setting the portal button text color	`rgb(255,255,255)`
`position`	A string setting the position of the portal interface panel on the screen	`CENTER`

The position property accepts the following options:

TOP_LEFT
TOP_CENTER
TOP_RIGHT
CENTER_LEFT
CENTER
CENTER_RIGHT
BOTTOM_LEFT
BOTTOM_CENTER
BOTTOM_RIGHT

Portal Assets

The Signiant Platform API allows you to upload portal background images, logos, or favicons as portal assets. Assets uploaded via the API are stored in Signiant-provided cloud storage and can be used to customize portals.

Once a request to the Platform API is accepted, the response will include an assetId, API endpoint and bearer token authorization to upload an asset to storage.

Note: File names are renamed to the assetId for security purposes. The optional description field can be used to note the file name or add a description to identify the image when using the API.

Asset Type Requirements

All portal asset types can be uploaded to Signiant-provided cloud storage, and are limited in size and resolution based on the asset type:

Portal background images must be PNG, JPG, or GIF format with a maximum size of 10 megabytes and 1600 x 1280 resolution.
Portal logo images must be PNG, JPG, or GIF format with a maximum size of 5 megabytes and 160 x 160 resolution.
Favicons must be in ICO, PNG, JPG or GIF format with a maximum size of 100 kilobytes and 64 x 64 resolution.

All requests to upload an asset must be uploaded in binary and include the correct Content-type:

Asset Format	Content Type
JPG	`image/jpeg`
PNG	`image/png`
GIF	`image/gif`
ICO	`image/x-icon`

Uploading an Asset

To upload an asset:

Select an image to upload that meets the requirements for the asset type.

Make a request to the Platform API server to indicate the kind of asset you are uploading and a short description or title of the asset.

curl -X POST https://platform-api-service.services.cloud.signiant.com/v1/mediaShuttle/portals/{portalId}/assets \
 -H "accept: application/json" \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 --data "{"type": "LOGO", "description": "Example Logo"}"

Note: The above example adds a portal logo. For more examples, see the API documentation.

Using the response, create a new curl request using the url and authorization header provided in the uploadInstructions object, and the path to the asset in the request body as a data-binary:
```
curl -X POST <url> \
 -H "accept: application/json" \
 -H "Authorization: <authorization>" \
 -H "Content-Type: image/png" \
 --data-binary "@/path/to/asset.png"
```

Once the request is accepted, the response will provide information about the asset, including its assetId which is required to apply the asset to the portal:

{
  "storageLocation": {
    "bucket": "signiant-provided-storage-bucket",
    "region": "us-east-1",
    "path": "portals/11111111-150c-1111-9827-d101312aba20/public/11111111-94a3-1111-9cc7-7780da375e95.png"
  },
  "accountId": "1111111-11111-42f8-9f35-907934f744b3",
  "mimeType": "image/png",
  "downloadUrl": "https://example.com/portals/11111111-150c-1111-9827-d101312aba20/public/11111111-94a3-1111-9cc7-7780da375e95.png",
  "sigUpdateRegion": "us-east-1",
  "state": "READY",
  "uploadedOn": "2022-09-23T17:12:39.489Z",
  "lastModifiedOn": "2022-09-23T17:12:39.489Z",
  "sizeInBytes": "4259",
  "isInUse": false,
  "assetId": "11111111-94a3-4084-9cc7-7780da375e95",
  "createdOn": "2022-09-23T17:11:50.435Z",
  "dimensions": {
    "width": 160,
    "height": 46
  },
  "serviceId": "11111111-0470-4cf4-913b-897d821ef7f6",
  "msAccountId": "11111111-29cd-4dde-b84e-81901376f1b2",
  "portalId": "11111111-150c-4214-9827-d101312aba20",
  "description": "Example Logo",
  "type": "LOGO"
}

Applying Branding

Once you have determined the changes to make to a portal, you can update your portal by making a request to the /v1/mediaShuttle/branding API endpoint.

To apply portal branding:

Create a new JSON file specifying the branding changes:

{
  "interfacePanel": {
    "color": "rgba(224, 224, 224, 0.9)",
    "position": "TOP_LEFT",
    "fontColor": "rgb(255, 99, 71)",
    "borderColor": "rgb(255, 99, 71)",
    "buttonColor": "rgb(255, 99, 71)",
    "buttonFontColor": "rgb(255, 99, 71)"
  },
  "favIcon": {
    "assetId": "11111111-bfea-411c-a279-3488160611bb"
  },
  "logo": {
    "assetId": "11111111-4f89-4cd7-b6b7-5b2090a54c55"
  },
  "background": {
    "position": "CENTER",
    "assetId": "11111111-9f88-4520-9a38-40c1f51f6337"
  }
}

Note: The background asset property accepts a position setting that uses the same format as the interface panel properties.

Save the file as brandingChanges.json.
In your terminal or command prompt, navigate to the directory where brandingChanges.json is saved.
Use the curl utility to PATCH the /v1/mediaShuttle/portals endpoint including an access token in the header and newPortal.json as the request body:


curl -X PATCH https://platform-api-service.services.cloud.signiant.com/v1/mediaShuttle/portals/{portalId}/branding \
 -H "accept: application/json" \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 --data @brandingChanges.json

The response body contains the portal branding details, including all assets associated with the portal:

{
  "interfacePanel": {
    "color": "rgba(224, 224, 224, 0.9)",
    "position": "TOP_LEFT",
    "fontColor": "rgb(255, 99, 71)",
    "borderColor": "rgb(255, 99, 71)",
    "buttonColor": "rgb(255, 99, 71)",
    "buttonFontColor": "rgb(255, 99, 71)"
  },
  "favIcon": {
    "assetId": "11111111-bfea-411c-a279-3488160611bb"
  },
  "logo": {
    "assetId": "11111111-4f89-4cd7-b6b7-5b2090a54c55"
  },
  "background": {
    "position": "CENTER",
    "assetId": "11111111-9f88-4520-9a38-40c1f51f6337"
  }
}

To remove an asset, send a PATCH request specifying the asset type, and set its value to null:

{
  "logo": {
    "assetId": null
  }
}