Bynder

Bynder’s AI-powered digital asset management platform enables teams to manage proliferating content, touchpoints, and relationships efficiently. It unifies and transforms the creation and sharing of brand assets.

After you’ve installed the Bynder app, allows editors to select media from their Bynder account directly within Contentful, enabling design and marketing teams to easily access and link their most recent assets.

Apps Bynder dialog updated

Overview

The Bynder app is a widget that allows editors to select media from their Bynder account. Click Select a file on Bynder and select the assets you want to be referenced from your entry. Asset data from Bynder is stored directly in your content entry as a JSON field, which your developers can reference directly from Contentful's delivery APIs.

The IDs of selected media are then stored in Contentful. Inside your client application, you then fetch content from Contentful and resolve all needed details on media by using the IDs to fetch binaries or metadata from Bynder’s API.

Requirements

To use this app, you will need:

  • The URL of your Bynder account.

  • A content type with a field of type JSON object to store Bynder asset references.

  • Bynder Client ID and Client Secret configured in the app settings.

  • OAuth2 client credentials from Bynder with API access privileges.

Permissions

The following permissions and scopes must be enabled:

  • Ability to view assets and portal insights.

  • grant_type: Client Credentials.

  • scopes:

    • asset.read

    • asset.usage:read

    • asset.usage:write

Usage

Step 1: Select mode

The app offers two modes for asset selection:

MultiSelect mode

  • Default mode.

  • Allows content creators to select multiple assets at once.

  • Does not support derivative selection or transformations.

  • Recommended for most users.

Your frontend should rely on the src parameter or similar Bynder URL fields.

SingleSelectFile mode

  • Allows selection of one file at a time.

  • Supports derivative image selection and in-app transformations (if CX Omnichannel is enabled).

  • Provides a selectedFile attribute in API responses.

Your frontend should rely on the selectedFile.url parameter to render the final image. If transformations are applied, this URL will point to the transformed asset.

Step 2: Prefill selected assets mode

On the configuration screen, you can choose whether new asset selections append to or replace the existing assets in your entry.

Default (“Prefill selected assets” = No)

  • Selected assets are appended to the field.

  • Assets can be added multiple times.

  • Saved assets are not preselected when reopening the picker.

Prefill Mode (“Prefill selected assets” = Yes)

  • Newly selected assets replace all existing assets.

  • Assets cannot be saved more than once.

  • Previously saved assets are preselected in the picker.

Step 3: Install and configure

  1. Under Configuration, provide your Bynder account URL.

  2. Assign fields of type JSON object to the app.

  3. Choose your selection mode (MultiSelect or SingleSelectFile).

  4. Choose your prefill behavior (“Yes” or “No”).

  5. Configure your Bynder OAuth2 credentials (Client ID and Client Secret).

If SingleSelectFile mode and TransformBaseURL are used, API responses will include transformation parameters such as height, width, and gravity for the selected derivative.

Apps Bynder installation screen

Click Install to finish the installation and save the configuration.

Step 4: Using the App

Multi Select mode

Apps Bynder select file on Bynder

To reference an asset on Bynder from your entry:

  1. Click Select a file on Bynder.

  2. Select the assets in Bynder using the dialog.

  3. Click Add Asset.

Apps Bynder dialog updated

Your frontend developers will receive a JSON payload containing a parameter similar to "original": "https://BRAND.getbynder.com/~/file.jpg". It is recommended that they use the original or src fields to pull assets. The specific fields available in this response may differ based on your specific Bynder configuration and package.

Apps Bynder selected assets in field location

Previews of your assets will now appear in your entry. You can also click on “More details” to see the asset name and id.

Apps Bynder selected assets more details

Single File Select Mode

To reference an asset on Bynder from your entry:

  1. Click Select a file on Bynder.

  2. Select the assets in Bynder using the dialog.

  3. Either select a derivative or transform base URL, and make any necessary transformations.

  4. Click Add Asset.

Bynder Single File Select

Your frontend developers will receive one of two JSON payloads containing a selectedFile attribute. In both cases, your developers should pull the  `url` parameter under the `selectedFile` parameter to get the accurately transformed image.

If SingleSelectFile mode and TransformBaseURL are selected with a custom transformation, the response will include parameters on the transform url that provide the requested height, width, transform type, and gravity. If SingleSelectFile mode and TransformBaseURL are selected without a custom transformation, you will receive parameters for height, width, and filesize as separate attributes.

Previews of your assets will now appear in your entry.

Asset Tracker

The Asset Tracker automatically syncs Bynder asset usage with Contentful entries by using Contentful App Events.

How It Works

  • Creates usage records when entries are published.

  • Updates records when entries are republished.

  • Removes usage records when entries are unpublished, deleted, or archived.

  • Tracks assets only in the master environment.

Configuration Steps

  1. Ensure Bynder Client ID and Secret with correct privileges are configured.

  2. Implement the provided Contentful function functions/asset-tracker.ts as the App Event backend handler.

  3. Configure App Events in Contentful to trigger the function for publish, unpublish, delete, and archive events.

  4. Verify Bynder OAuth2 credentials have scopes for the Asset Usage API.

Note: Asset tracking requires properly configured Bynder OAuth2 credentials with the necessary scopes (asset.read, asset.usage:read, asset.usage:write) to function correctly.

FAQ

There are no content types with JSON Object field, help!

Bynder saves data into a Contentful entry using JSON data. If you'd like to associate Bynder assets with a specific content type, you must update that content type to include a new field which is of type JSON Object. Learn more about the JSON Object field type in our concepts documentation.

What to do if the entry editor displays the warning Field value is incompatible?

The "JSON object" field of this entry already contains data that was not generated by the Bynder app. Please ensure that you've selected the correct field in the app configuration to be used with Bynder, and that you do no longer need the previously entered data. Then select I want to override the value using the App., which will initialize the field with an empty selection. Now you can start to add media to your entry.

To access the underlying field value, deselect the field in the Bynder app configuration. This will reset the editor to the default json display for object fields.

How do I access the URL of the original asset?

Availability of the URL of the original asset in the JSON payload depends on making an asset public in the Bynder Portal. In order to make an asset public, you need to go to the "Edit" section in your Bynder Portal and then under Advanced Rights, you need to select the Mark as public option. As soon as the setting is saved, the JSON payload will include the orginal property pointing to an unmodified asset.

I see odd behavior when switching from Single to Multi Select (or in reverse)!

If you select Single Select or Multi Select in the Bynder App Definition, you may see unpredictable behavior when switching this choice later on. The Single Select option provides an additional parameter for the images you select (selectedFile) that is not available on Multi Select. If you rely on this parameter for some part of your site, you will see unpredictable behavior on existing entries if you change selections.

We recommend choosing and staying either Single or Multi Select exclusively.

How do I see additional details about the selected assets?

You can see previews of selected assets in the Bynder field editor. You can also click “More details” to reveal the asset name and id. Additional data for each asset is saved in JSON in the field, and can be accessed via our APIs.