Wedia Content Picker

General presentation

The Wedia Content Picker is an easy way to pick asset from Wedia and insert them in your web application.

Wedia provides ready to use Content Pickers for :

Additional content pickers are available on request, please contact your Account Manager for more information.

 

If your “host software” is not available, you can build your own integration by using our standard Wedia Content Picker interface. It is designed to be embedded in web application through a Javascript integration, and return a JSON object containing the selected media(s) metadata along with the url / embed codes of the image or rich media (video, …)

A test Content Picker is available here : https://wedia-content-picker.wedia-group.com

This documentation describes how to build your own integration with the Wedia Content Picker interface.

Wedia Content Picker Goals

The Wedia Content Picker goal is to be integrated in an external software, such as a CMS or a PIM. System integrators can wrap it in places where the user should pick an asset, and will get a secure, CDN backed, integration code of the asset, or a link to the asset binary.

 This integration code can be exposed in a high traffic website, and will serve the selected asset.

Wedia also provides some out of the box wrappers for Microsoft Powerpoint, Microsoft Word and Microsoft Outlook, detailed here : https://crossmedia.atlassian.net/wiki/spaces/WD/pages/339345553

The Wedia Content picker shares most of the code and the setup configuration with the DAM Portal, and runs on the  infrastructure that delivers the DAM Portal. 

Screens and workflows

Login Screen

The login screen is mandatory, except when the DAM is set up with an “open access”. 

If the DAM is not set up as “open access”, the Content Picker will require a login to access the asset list.

SSO methods can be set up for currently SAML (tested with Microsoft Azure IDP), OAuth2 (tested with Google).

User registration is currently not opened on this screen. If you are interested by this option, please get in touch with us.

The user can search using filters and full text search assets.

Depending on the screen resolution, the picker can show or mask the filter line using parameters.

Example with filters : 

Example without filters :

Previewing an asset

To preview an asset, users can click on the eye button on the overlay of the asset : 

This will show a player with the asset detail :

If the media is a video, a video player is shown : 

Optionally, the preview can display some metadata on a right column, or below the image, depending on the screen resolution, and offer a “copy credits to clipboard” option : 

 



Selecting a single or multiple asset

If the selection mode is set to “single”, a “integrate” button is displayed on each asset on the list and triggers the select action, that will return the message to the originating window with the information of the selected asset: 

 

If the selection mode is set to “multi”, a selection box is shown on the top right of the asset :

Selected items will be displayed on the bottom bar selection area:

Clicking on the “Check” button on the bottom bar will trigger the selection action and return the selected media asset.

If the Content Picker is setup in that way, the user is then given the opportunity to Crop / Focus the image with a preset H x L for single picking only :

If the focus point option is enabled, the user is given the opportunity to click and set a focus point that will be reflected in the output format :

 

Required Versions and setup

The Wedia Content Picker is available starting from Wedia version 11.26, with MediaCloud enabled and MediaDelivery enabled on the client instance.

The Wedia Content Picker is a VueJs application that rely on the same REST API used for our portal implementation.

The Wedia Content Picker setup includes mandatory steps that are mostly carried out by the Wedia Professional Services :

  1. Upgrade to Wedia version 11.26

  2. Ensure the client datamodel is compliant with the portal, and upgrade it if necessary

  3. Enable MediaCloud for this client

  4. If the assets are going to be publicly published, enable MediaDelivery for this client

  5. Setup Security rules to know which medias can be broadcasted

  6. Activate the Vue-Portal plugin which contains the Content Picker

  7. Edit the JSON parameter files of the DAM Portal : client-general-information, global, signup, available-filters… This is usually done by the Wedia Service team.

  8. Edit the JSON parameter file for the Content Picker : list of the metadata that will be returned in the oEmbed 

The Wedia Content Picker setup includes also optional, but recommended steps.

  1. Creating dedicated roles for the users that will use the content picker, such as “Webmaster”, “Social Media Manager”. 

  2. Setting up filters in the portal configuration file when the content picker is set up to display filters in the UX

  3. Setting up “cursors” for prefiltering assets. For example, the content picker can be called with a specific cursor such as “only image, expiring in more than 3 months, of hero images of products, with a minimal width of 1920px”

  4. Setting up preset variations of the returned images, such as “PNG, SQUARE, WHITE BACKGROUND”.

  5. Skin the video, document, ... player with custom colors, logos...

Including Wedia Content Picker in your web applications

The content picker is invoked through a Javascript script that opens an iframe with the Wedia Content Picker and communicates with it.

<script src="https://client-name.wedia-group.com/asset-picker/wedia-content-picker.js"></script>

The script exposes an new API where you can attach (append to is the exact DOM action) the content picker to a empty DOM element :

WediaContentPicker.attach({ el: yourDOMelement, server: "https://client-name.wedia-group.com" onPick: function(assets) {  /* your actions with the array of selected assets */ }      … other parameters : see below. })

This is creating an iframe pointing to the Wedia Content Picker, and attaching it (inserting it into exactly) to the dom element.

The onPick function gets called when the user selects either one or multiple assets. 

The iframe is not removed after success, it is your duty to take care of that by removing the element that the Wedia Content Picker is attached to.

Settings

All settings are optionals.

They are passed in the attach call, as numbers, boolean, strings or array of strings.

WediaContentPicker.attach({ el: yourDOMelement, server: "https://client-name.wedia-group.com" onPick: function(assets) {  /* your actions with the array of selected assets */ }, assetNatures: "IMAGE,VIDEO" })

Attribute

Description

Possible values

Default

UX modifiers

assetNatures

A list of selectable asset types, in uppercase, comma separated

ALL (tous les types)

ou un ou plusieurs type primaire séparé par une virgule, parmi : IMAGE, VIDEO, 3D, AUDIO, DOCUMENT, PRINT, ZIP

“IMAGE”

min

The minimum number of assets that the picker should return.



For a single pick, set this value to 1, and the max to 1



For multiple set this value up to 100

a number ranging from 1 to 100

1

max

The maximum number of assets that the picker should return.



For a single pick, set this value to 1, and min to 1



For multiple set this value up to 100

a number ranging from 1 to 100

1

lang

The language of the UI

“en” , “fr”, “de”

browser language

showPreview

if we should display the “preview” button, and the preview popin window

true / false

true

showFilters

if we should display the filter bar

true / false

false

showSort

if we should allow asset sorting

true / false

false

showCursors

is we should display the cursor options in the UI. These cursors are set up in the Wedia Portal configuration





true / false

true

showCropper

The user can crop the image to either an expected dimension (expectedWidth

expectedHeight)

true / false

true

showFocus

The user can select the focus points on the image.

true / false

false

showLayout

Show the different layout choices (line, columns, details, square…)

true / false

false

Expected return formats

expectedWidth

expectedHeight

Wedia implements a cropper that will return a virtual cropping of the image.

If expectedWidth and expectedHeight are present in the configuration object, the cropper will show up for single picks.

This will not exclude from the search the images that are too small to comply with these constraints.

the expected width / height in pixels



variation

Wedia implements preset media renditions, called variation :  for example thumbnailReal is the rendering of the image at its original size, in JPEG or PNG, depending on the server configuration.

There are product presets, and project presets : using Java extensions, or Admin back-office, system integrators can defined project defined presets, such as : a watermarked image with a white icon horizontally centered at 10 px from the top…

Read more on how to define a custom variation here.

 

Videos, 3D, PDFs are returned in a player HTML component, so no variation is needed, and this variation should be left blank.

But If you need to get the actual binary of a video, you can set the variation of the video among “SD”, “MD”, “HD” quality.

 

If you are allowing the user to pick mixed formats such as VIDEOS and IMAGES, default renditions will be applied to your return set : thumbnailReal for images and a HTML player for videos

The expected variation

“thumbnailScreen” (a 2000 pixel wide web preview) 

additionalVariations



A list with the names of the possible variations. Comma separated



playerId

if a video specific player among those defined at the project level should be selected

a string of the player name as defined in the Wedia Player Manager

“default id”

playerWidth

the specific width of a video player in  pixels

an integer between 150 and 2000, or a percentage

560

playerHeight

the specific width of a video player in  pixels

an integer between 150 and 2000 or a percentage

315

playerAutoStart

for the few browsers that still support it, should the video start automatically

true / false

false

playerShareLinks

enable the social shares in the player

true / false

false

enableImagePlayer

Images can be embedded in a player with a zoom, social sharing. This is not a common use case, but can be enabled. In that case, the “variations” parameter will be ignored 

true / false

false

Search filters

cursor

a cursor is a predefined request that filters assets in order to show a restricted set of assets. The user cannot override this restriction.

Cursors are set up at the Wedia level, they have a name and a query.

For example : productHeroImage : select all product images that have an expiration date set over 4 months from today and that have a width over 1600 pixels

The name of the cursor as defined in the JSON parameter files of the Wedia Portal config



fullText

a preset full text query. The user can remove this query.

the text of the query



Advanced

configPath

If you want to define totally different pickers, this can point to multiple JSON portal config. this is an internal option to be discussed with your Wedia product specialist when you need really different JSON parameters, such as the metadata displayed in the preview popup, cursor names...

the internal path to the JSON portal config.

/res/contentPicker



Returned values when a user selects one or more assets

When the user selects one or more assets, the “onPick” function gets triggered with a message containing information about the picked media selected, and the rendition selected.

The result is returned in a collection of oEmbed entities which is well suited for this information : https://oembed.com/. We comply with the basic format, and expand it with specific properties prefixed with “wedia”.

 

{ mode: "single | multiple", entities: [ { version: "1.0", title: "Seaside road in Florida", url: "https://club-wed.wedia-group.com/api/wedia/dam/transform/8muczkpi73bhwtc6zw3qnt7s7h/out?t=crop&x=0.206&y=0.000&width=0.736&height=0.589&outputWidth=500&outputHeight=300", type: "photo", width: 500, height: 300, wedia_variations: [ { name: "circle_png", url: "https://club-wed.wedia-group.com:443/api/wedia/dam/variation/8muczkpi73bhwtc6zw3qnt7s7h/circle_png,default", filesize: 3726375, width: 1500, height: 1500 }, { name: "cropped", width: 500, height: 300, url: "https://club-wed.wedia-group.com/api/wedia/dam/transform/8muczkpi73bhwtc6zw3qnt7s7h/out?t=crop&x=0.206&y=0.000&width=0.736&height=0.589&outputWidth=500&outputHeight=300" } ], wedia_metadata: { $uuid: "8muczkpi73bhwtc6zw3qnt7s7h", resource: "asset", id: "26", name: "Seaside road in Florida", keywords: [ { id: 797, $uuid: "f9q3beyefhurnhm7wceg5c4nqfn37xj1hfd5p5a", name: "sea" }, { id: 835, $uuid: "f9q3beyefhurds5c8mrapw9zobn37xj1hfd5p5a", name: "drone" }, { id: 831, $uuid: "f9q3beyefhurdt6ufamabdi33jn37xj1hfd5p5a", name: "sky blue" } ], width: 3780, height: 2835 }, wedia_cropInfo: { xPct: 0.2057351030060291, yPct: 0, widthPct: 0.7356622424849274, heightPct: 0.5885297939879419 } } ]

Processing the information returned by the Content Picker for Images

When the user select an image, the JSON helps you create IMG SRC you can use.

The default URL is returned at the top of the JSON content :

But very often, you want to have better control on naming the file, or generation SEO content.

To manually create the IMG SRC, follow this pattern :

[SERVER BASE URL]/api/wedia/dam/transform/[UUID]/[BASE VARIATION]/[FILE_NAME][.FILE_EXTENSION]/t=[TRANSFORMATION]&[CROP PARAMETERS x=XPct&y=YPct&width=widthPct&height=heightPct&fx=x&fy=y]&outputWidth=[OUTPUT_WIDTH]&outputHeight=[OUTPUT_HEIGHT]

For example:

https://club-wed.wedia-group.com/api/wedia/dam/transform/cr64xkzf18c9357ct4okkmpf8r/stripped_background/out.png?t=crop&x=0.000&y=0.050&width=1.000&height=0.900&outputWidth=500&outputHeight=300

 

SERVER BASE URL: It is equal to the URL of the Wedia server.

UUID: It is equal to the value of the $uuid property in the wedia_metadata property.

BASE VARIATION: It allows starting the transformation based on a given variation. Usually, this parameter is empty, and the transformation always starts from the best variation. The best practice is to omit this parameter.

Usage example of BASE VARIATION :

If you would like to benefit from a variation that has its background removed by an AI, then the BASE VARIATION should be set to "stripped_background", that is the variation of the image that was processed by AI to try to remove the background to isolate the subject on a transparent background.

 

FILE_NAME: It is the file name served to the browser. If not downloading the image, which is the most common case, then it only serves for SEO referencing.

To achieve good SEO referencing, the following procedure is advisable

The file name is composed, in order of priority:

If in wedia_metadata "name + locale" exists and is not empty (for example, namefr for an article in French), then use name + locale:

If in wedia_metadata "name" exists and is not empty, then use name

If in the name in wedia_metadata, then use title.

You may also add keywords coming from wedia_metadata. All keywords are added after the name, separated by hyphens.

The final file name, name + keywords, is encoded to account for accents and spaces.

 

.FILE_EXTENSION: Allows specifying a specific file format, for example .png, .jpg, .webp. Leave it empty to benefit from Wedia's ability to return the best file format based on the browser's capabilities (usually WebP).

 

TRANSFORMATION: There are several types of transformations, for the content picker return we systematically use the value: crop

The complete reference guide is available for working with other transformations is available here :

 

CROP PARAMETERS: The values to fill in are found in sections of the Json:

wedia_cropInfo for cropping parameters:

and

wedia_focusInfo for focus parameters.

These parameters should be omitted when they are not specified in the output stream.

 

OUTPUT_WIDTH

OUTPUT_HEIGHT

This is the desired final height / width of the image. If it was passed as a parameter in the Content Picker invokation, it is returned in the returned JSON

 

Adding custom variations for complex image manipulations (watermarking…)

The offers simple transformations such as cropping and resizing via URL parameters, such as t=crop…

You may want to go further, and apply complex transformations such as text watermarking, recoloring etc.

In that case, you need to set up a new “rendition” of the image in the Administration part of the system, and request them in the input parameters of the content picker, in the “variation” or “additionalVariations” parameters.

In that case, the Wedia system will return the results as an arry in the wedia_variations objects in the returned Json.

Please follow this documentation to set up custom variations.

 

Processing the information returned by the Content Picker for Videos

 

When the user picks a video, the Json returns an embed code, as an iFrame, in a html property.

Please note that you can add in the requested variations two useful variations :

ia_preview_video_source will return a small mp4 video loop, highlighting the most interesting scenes of the video, processed by our AI.

thumbnailBigAuto will return a poster image of the video, 600 pixel high.

To use them, add ia_preview_video_source,thumbnailBigAuto in the additionalVariations parameter when calling the Content Picker.

 

Analytics and tracking (optional)

To keep track of who picked the asset to be used in an external system, an analytics API can record the pick list and add a custom “web_publish” event in the analytics.

This out of the scope the document, please refer to the documentation of this API :

https://club-wed.wedia-group.com/api/wedia/analytics/?export=redoc#tag/add