Wedia Content Picker
- Olivier Grenet
- Simon MINOTTO (Unlicensed)
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 : Wedia Office 365 Content Picker
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.
Asset list and search
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 :
Upgrade to Wedia version 11.26
Ensure the client datamodel is compliant with the portal, and upgrade it if necessary
Enable MediaCloud for this client
If the assets are going to be publicly published, enable MediaDelivery for this client
Setup Security rules to know which medias can be broadcasted
Activate the Vue-Portal plugin which contains the Content Picker
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.
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.
Creating dedicated roles for the users that will use the content picker, such as “Webmaster”, “Social Media Manager”.
Setting up filters in the portal configuration file when the content picker is set up to display filters in the UX
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”
Setting up preset variations of the returned images, such as “PNG, SQUARE, WHITE BACKGROUND”.
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:
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.
To better understand base variations : Digital Asset Transformations and Delivery API | Using a built in variation
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 Digital Asset Transformations and Delivery API 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