Smart Asset Embed

If you are running an eCommerce site or product-orientated CMS website then you may have the tedious and error-prone task of uploading all of your product imagery both to Brandworkz so it's accessible to partners, resellers, etc. and then uploading the images again to your eCommerce system and other systems like a PIM or CMS. If your eCommerce system doesn't have automatic image transcoding you may even have to manually prepare multiple resolutions of each image and upload these.

Also, if there down the line are updated or retouched versions of product shots already in use you will then of course also have to upload these in multiple places, creating more work and scope for human error.

With the Smart Asset Embed feature you can upload just a single high-res version of each image to Brandworkz, tag them and then create smart embed links which will automatically generate and display the correct images in the resolutions you need across your entire product range.

Assuming you have all your product photography uploaded and tagged in Brandworkz then you can auto-generate image permutations for ALL of your products via a single smart link generated from Brandworkz which you as a Web-developer paste into your eCommerce template in appropriate places as a one-off exercise!

At no point do any images get copied/synched to your eCommerce software, they are all served by Brandworkz via a CDN (which can be mapped to your own web domain), enabling automatic swap out when an asset has a new version - e.g. a post-launch retouch - , and pulling of content and alerts on assets that have expired.

Example

Let's imagine you are a company selling shoes and boots from your eCommerce site. Your product detail page for a particular boot may look like this when it loads:

... when the end-user hovers over the main image, typically a high-res version will show up so they can see the detail.

... and if the end-user clicks on one of the small thumbnails at the bottom it will change the main image to the angle shot clicked on.

... and finally, if the end-user clicks on one of the colour tabs then all of the images will change to the selected colour:

In the above case this is a grand total of 6 angles X 3 resolutions X 3 colours = 54 files.
... and then you may need additional resolutions for mobile display and perhaps some lifestyle images showing the product in use so before you know it - or perhaps you are already painfully aware - you are up to around 100 files for each product that need to be manually prepped and uploaded!

If you are already uploading a high-res version of each shot to Brandworkz and tagging them, the eCommerce embed link feature can completely negate the need for you to upload images separately to your eCommerce or CMS site.

A product listing or detail page will always be based on an underlying template which is typically the same for all products or there is a low amount of templates to choose from. On this page there will be a number of programming variables available for the developer to use when displaying the page such as price, colour options, size options, description etc.
The ones we are interested in for image purposes are:

• SKU i.e. the unique product code - For the boot above this is 21610070
• Colour: For the boot above this is "Graphite grey ", "Tan" and "Wine" 
• Shot Angle: In the case above this may not be a programming variable but simply something the template designer hardcodes into the template because he/she knows that all boots and shoes will need to be displayed from these fixed angles:
  Hero (i.e. the best-looking angle), Left, Right, Top, Front, Back

For the eCommerce image integration to work, you will of course have to have your product images uploaded into Brandworkz, and for this example you will also need to have them tagged with the above three tags. The names of the tags don't have to be identical to the corresponding programming variables you have available on your eCommerce template, but if they are the same or similar this will make things more logical, so we strongly advise to coordinate your metadata fields/taxonomy between your Brandworkz instance and your eCommerce system.

Set up and configuration

Prerequisite step 1: Set relevant folders to have pre-generation enabled

• Log in to Brandworkz as a sysadmin
• Go to Settings -> Smart Asset Embed
• Expand the Brandworkz folder tree and tick the folders which have - or will have - the images in which will be used for your public site.
  Note that you should not enable this for all folders if not relevant as it will be wasteful in terms of extra storage for image permutations never used, and additional CPU for image transcodes which will never be used. Note that you can still do image transformation in other folders, but this is done at the point in time of end-users requesting them. eCommerce permutations must be pre-generated as e.g. on a new eComm site launch, tens of thousands of images may be accessed immediately so they need to be ready.
  In the below example screenshot it's just the 'ecommerce' folder which is set for pre-generation as other folders don't contain images for eCommerce/online use
• Click 'Update Pregeneration folders'
• Go back to the main Settings page

Prerequisite step 2: Set up the Image Transform Wizards needed for your eCommerce front-end

You will likely need the images to be generated to one or more pixel sizes, which you can get Brandworkz to do through it's Image Transform Wizards feature.

• Log in to Brandworkz as a sysadmin
• Go to Settings -> Image Transform Wizards
• Click Add new transform wizard
• Give the wizard a name -e.g. 'eComm - Large'
• Untick 'Asset download'
• Tick 'Embed link'
• Enter a 'System Name' for the transform. You would typically keep this short, and you also can't use spaces or non-standard characters. In this case you could just call it 'L' for Large
• Keep 'Pregenerate output' to Enabled - this will ensure that when new images are uploaded to folders marked for pregeneration, that this particular permutation will be generated immediately after upload so it's ready to use on your public site without delay.

Please Note: that you can enable wizards for pregeneration retrospectively, but this may create a large queue of image generations that will then need to be processed before this size can be used publicly.

• Untick 'Show on Download' dropdown - as you typically don't want this size to be downloadable by end-users of the system
• Enter the format, compression, colour space settings appropriate for the output you need.
  e.g. Jpg, 90 compression, RGB, 'Fit within Height & Width below', Width: 1000, Height: 1000 (see screenshot below)
  Do not tick multiple formats, colour spaces. This is only relevant for transform wizards targeted for human end-users who then gets a choice when using it.
• Repeat the above steps for the different sizes you need. You can create up to ten.
  Remember that there is a balance to be struck between generating lots of different sizes that are exactly the same pixel size as the visual size, vs. creating fewer sizes and then scaling them front-end with CSS. You would typically not create more than 2 or 3 sizes for a product detail page, and if you needed to show it in more sizes visually, you would scale them with CSS front-end. This will minimise the kb download size for the images needed on a page.

Prerequisite step 3: Set up an eCommerce metaset/taxonomy

Setting up tagging/metadata fields aren't covered here as this is covered in this article.
You may have one set up already, or you need to create one. Keep in mind that this taxonomy must be the same as the one you are using in your eCommerce software and ideally also your PIM/MDM (Product Information Management/Master Data Management) solution if you have one of those.
The fields would typically be something like this (colour, Product Code/SKU, etc.)

Prerequisite step 4: Upload your product images and tag them if you haven't done so already

Upload some or all of your product imagery and tag them so they are - at a minimum - tagged with the fields which is required to decide which image(s) to show where. This would almost certainly be Product Code/SKU, and also often Colour, Angle and Hero-shot.

Step 5: Generating the Smart Asset Embed link:

• Log in to Brandworkz as a sysadmin
• Go to Settings -> Smart Asset Embed
  
  

• Scroll down to the Embed Link Builder and choose the size/transform wizard you want to use from the drop down.
  If its not showing go to Settings > Transform Wizards and check the one you are after is set to usage type 'Embed Link' and its been enabled for pre-generation output.

• Choose a return type of Single asset (see tip further down for use of JSON return type)

• For optional built in filters choose 'Image', and optionally limit to Landscape or Portrait if you only want either portrait or landscape images returned.

• From the 'Metadata filters' dropdown select the metaset that is applied to the folder that has the images in which you want to use. 

Please note: only metasets that are applied to folders set to pre-generation will show in this list. If the metaset you are looking for is not listed it's probably because it's not been applied to a folder that is set to pre-Generation.

• Select the metadata fields you want to filter on - i.e. which ones determines the image(s) that should be returned - and click 'Generate link'.

• Using the above examples you should now have a link which looks like this:
  //clientcdn.brandworkz.net/bms/embed/qs/?s=l&PRODUCTCODE_e33e8034-f4c8-492e-945f-0f2b40daf8c6=XXXXXX&SEASON_9961c217-4b54-41d0-80a2-93919a13d5af=XXXXXX&SHOTANGLE_9e6a4a99-5599-4e99-b913-a0c740065e88=XXXXXX&ft=Image
  
  

Alert

Note that these links are NOT for pasting in somewhere in your backend admin for each product, they are for the web developer to paste into your CMS/eComm templates as part of the site build/update as a one-off exercise. 

Once this is done, all of the image admin is done via Brandworkz.

It might also be useful for the web developer to add these links to the backend admin page when editing/adding products, so they will output as read-only images on the product admin page. That way it's very easy to double-check which images will display prior to launching the product - and indeed if nothing shows, then the related images will have to be uploaded and tagged in Brandworkz first as this hasn't been done.

Lets dissect the link above

• //
  This notation signifies that if the link is running from a page over http then it will match the page's http protocol, and correspondingly if the page is running over https then it will also correspondingly ask for the image over https:// 

Tip

If you are on a Mac and paste the URL directly into a browser for testing purposes you may need to replace the '//' with 'http://' or 'https://' as otherwise the browser will assume that it's a file on your local machine and just show an error. 

• clientNameCDN.brandworkz.net
   A CDN (Content Delivery Network) link which is tied back to your Brandworkz instance. This is in order to provide infinite, rock-solid scalability of the image serving in case your site is very busy. A CDN also has the added benefit for global sites with users in several countries that the images will be copied out to server "nodes" geographically closer to their location and therefore load faster for them, especially if they are far away from the origin/hosting server (e.g. server is in the UK and user is in Australia)
• /bms/embed/qs
  Simply the path to the script on our servers which processes the below URL variables and returns a matching image
  Note that behind the scenes, the script is using our search engine to find matches to the below filters.
  If there is more than one match then it will return the highest-ranking one.
  See further down for returning and outputting multiple images matching a criteria (rt=json)
• ?s=l
  Reference to the transform wizard, aka. the size/resolution/format.
  As mentioned you need to set up the sizes you need on your front-end pages as transform wizards which have the usage type "Embed link" ticked.
  When you paste the Embed link into your template, you will typically paste the link a number of times and then change the size parameter relating to the size(s) you need to output on that particular page.
• PRODUCTCODE_e33e8034-f4c8-492e-945f-0f2b40daf8c6=XXXXXX
  A filter to limit down to a particular Product Code. Note that the GUID is our internal identifier for the Product Code field. This part of the URL variable needs to be retained. The GUID also makes the system safer as it will be impossible for a hacker to second-guess other tagging fields in an attempt to return different images.
  When you as a developer paste the link into your eCommerce template you will then replace the XXXXXX with the corresponding programming variable in your eCommerce system
  i.e. PRODUCTCODE_b42b3ca5-e6b1-42a1-bf93-e18c804c6d74=$PRODCODE (or however the Product Code variable is referred to in your system)
• SEASON_9961c217-4b54-41d0-80a2-93919a13d5af
  Same as above but for season
• SHOTANGLE_9e6a4a99-5599-4e99-b913-a0c740065e88
  Same as above but for the angle. As mentioned this may not be a variable in your eCommerce template, but simply something you hardcode into your template. In our boot example above there are 7 fixed angles (including the Hero angle which is used for the initial large image). In this case you would copy out the embed link 7 times in relevant parts of your code and then change the angle to Hero, Front, Back, etc.
• ft=Image
  Returns an image
  

For instance:

• For the default main image showing the "Hero" angle the link would be like this://clientNameCDN.brandworkz.net/bms/embed/qs/?s=l&PRODUCTCODE_e33e8034-f4c8-492e-945f-0f2b40daf8c6=$PRODCODE&SEASON_9961c217-4b54-41d0-80a2-93919a13d5af=$Season&SHOTANGLE_9e6a4a99-5599-4e99-b913-a0c740065e88=Hero&ft=Image
• For the zoomed/hover image this would be the same but with the "s"/size parameter set to XL (or whatever the systemref is of the size you are using for the zoomed image)
• And for the other angles you would replace the Angle parameter.

Built-in filter fields

Here is a description of what all of the built-in filters are for (shown at the bottom of the list below the custom fields)

• fileType: Image
  Limit results to Images  
• fileType: Document
  Limit results to - image thumbnails of page 1 of - Documents  
• fileType: Video
  Limit results to - image thumbnails of a still-frame 2 seconds into the video of - Videos
  
• Return all matches as json
  You can add &rt=json (returntype) to get json back instead of an actual image. This json will contain references to all of the matching images. This can be used for debug/testing purposes, but you can also use this return format to then further process the json within your eComm/CMS template. For instance if you have a product range where you have an unknown amount of non-hero images, e.g. some products have none, others have five, etc. you can use the JSON return format to get all of the matching images back for a particular product SKU, loop over it in your code and output as many images as are returned by Brandworkz - i.e. the images tagged with the current product's SKU in Brandworkz.

Note:  even though the return of the json from Brandworkz is fast as it's cached on the CDN, you would likely also want to employ a caching mechanism on your page level, e.g. every 5 min, to ensure that the rendering of your product pages is fast.