Integration with Akeneo

Deliver perfectly optimized images from your Akeneo PIM to your websites and apps in a blink of an eye.

Introduction

What is TwicPics?

TwicPics is a real-time media processing service that enables developers and companies of all sizes to deliver rich and optimized visual content to their website.

TwicPics is more precisely a Responsive Image Service Solution (SaaS). It offers on-demand responsive image generation combined with a well-thought-out and unobtrusive JavaScript library, all based around a URL-based API.

Akeneo Integration

Depending on your Akeneo version, TwicPics provides you with :

• TwicPics Akeneo App for an immediate integration of your PIM assets.
• TwicPics Akeneo Connector which allows to define your PIM as the source of your assets.

In both cases, assets from your PIM will be optimized and served by TwicPics in your websites and applications.

Want to know more about TwicPics? Click here for more information.

Requirements

Integration between Akeneo and TwicPics requires you to:

• Own an account (PIM) on Akeneo
• Own an account on TwicPics

Supported image types

Depending on your Akeneo edition, you can get and optimize these following image types from your Akeneo PIM to your websites and apps:

All editions

• The media files associated to Products (see Akeneo Product Media File documentation)

Enterprise Editions only

• The media files associated to Assets (see Akeneo Asset Media File documentation)
• The media files associated to Reference Entities or Records (see Akeneo Reference Entities documentation)

Features & benefits

The Akeneo TwicPics App and the Image Optimization Akeneo Connector for TwicPics allow you to benefit from the same features as if you were using TwicPics in the standard way.

• Media resizing and DPR: TwicPics automatically detects the DPR of your visitors. It means we automatically size your existing and future images and videos at the correct DPR for any device.
• Video Optimization: TwicPics videos are short, muted, auto-playing native HTML video elements. They enable integration of hero, product, and thumbnail videos. Refer to our documentation to learn to implement video optimization.
• Lazy loading: TwicPics automatically defers offscreen media to improve page loading time. It also offers images and videos placeholders functionality to deliver a better user experience.
• Many image formats processing: TwicPics supports non-animated AVIF, GIF, HEIF, JPEG, PNG and WebP formats for images, and can optimize any source video files up to 30 seconds, 30 FPS, 36 million pixels, 36MB.
• Next-Gen format conversion: by default, and for better optimization, TwicPics automatically converts your medias to Next-Gen formats (WebP, WebM, etc.) for all compatible devices.
• Lossless compression: TwicPics automatically removes useless data and compresses images and videos on the fly. Reduce image size by up to 75% without compromising its quality.
• Global CDN: serve your media closer to your users thanks to a worldwide CDN powered by Amazon™.
• Rock solid architecture: 99.999% service uptime and 99.99% image delivery success on average.
• SEO optimizations

Using Akeneo TwicPics App

Connect your PIM with Akeneo TwicPics App

1. From your Akeneo PIM interface, click on Connect page.
2. Click on App Store.
3. Search for TwicPics in the APPS section.

4. Click on Connect button: you will be redirected to TwicPics SignUp page, after going through the Akeneo authorization process.

5. Create your TwicPics account.

That's it. Your TwicPics account is now set up and ready to use.

Your first Akeneo workspace is automatically added to your favorites list. Click to open it.

Here is your workspace ready to use. It contains a first domain that we have also added to your favorites list. Click to open it and discover your first Akeneo path.

Your first path is operational. Optionally, you can modify its behavior by clicking on the 3-dot icon button (add a watermark, a default transformation, etc.)

You can now start distributing your assets in your websites and applications from your brand new domain https://my-company-akeneo.twic.pics, with my.company.cloud.akeneo.com being the name of your PIM.

Feel free to rename the automatically created workspace and domain.

TwicPics Akeneo domains

In your my company akeneo workspace, in addition to the classic TwicPics domains, you can create Akeneo domains which will be automatically associated with your PIM. They are identified by the Akeneo logo .

All TwicPics paths you create in an Akeneo domain are automatically configured with your Akeneo PIM domain as the Source URL and are ready to use.

From now on, you can begin integrating and optimizing your Akeneo PIM images to your websites and apps with TwicPics.

Using Akeneo Image CDN by TwicPics

The Image Optimization Akeneo Connector for TwicPics works with the Akeneo 1.7+ and Serenity versions, depending on which image types you need to request from your Akeneo PIM.

Akeneo PIM setup

The very first step to install the Image Optimization Akeneo Connector for TwicPics is to create a "connection" from your PIM interface. Refer to the complete documentation of Akeneo to see how you can create the "connection" that will connect TwicPics to your Akeneo PIM, or apply these following steps:

1. From your Akeneo PIM interface, click on Connect.

2. Then on Connection settings.

3. Click on the button Create that will redirect you to the "connection" creation form.

4. Here in the Label field, enter the name of the connector - this name could be TwicPics or TwicPics connector.

5. Choose the Flow type of your "connection" (see the official documentation for more information).

6. Grab your "connection" credentials (Client Id, Secret, Username and Password). Through the header authentication of the connector, they will be used to authenticate TwicPics' calls to Akeneo API and get your images from your PIM.

7. Set the proper permissions for both the user role and the user group (see the official documentation for more information).

TwicPics account setup

Create your TwicPics account

If you don't have any TwicPics account yet, you can easily sign up here for free.

With your brand new account comes a subdomain akin to <sub>.twic.pics that should has been created during the onboarding process. All your media will be delivered through this domain from now on.

Connect your TwicPics domain to your Akeneo PIM

From the "Domains" section of your TwicPics Workspace, click on the Create path button.

A panel will open, in which you must set the URL of your Akeneo PIM as the Source URL.

For instance, if your Akeneo PIM is located at https://<your-pim-subdomain>.akeneo.com then the Source URL must be set to https://<your-pim-subdomain>.akeneo.com.

Then, select the Akeneo Connector option as the source authentication to fetch your images from your Akeneo PIM.

And fill in the credentials of your TwicPics connector (grabbed from your Akeneo PIM) in the dedicated fields.

Click on the Add button located at the bottom right of the popup window: the newly created connection between your TwicPics domain and your Akeneo PIM now appears in the list of paths.

From now on, you can begin integrating and optimizing your Akeneo PIM images to your websites and apps with TwicPics.

Integrate your PIM images

To integrate and optimize your Akeneo PIM images with TwicPics, simply use your TwicPics domain (e.g. https://my-company-akeneo.twic.pics). The endpoint to use depends on the type of image to be optimized:

By products media files

• Endpoint: /media/<media code>, with <media code> being the code of the media file associated to a product.
• For instance: https://my-company-akeneo.twic.pics/media/<media code> could be https://my-company-akeneo.twic.pics/media/5/9/z/2/43z8b1586_DEMO_IMAGE.jpg.

By assets media files

Available for Akeneo Enterprise Editions only.

• Endpoint: /asset/<asset family>/<media code>, with <media code> being the code of the media file associated to an asset, and <asset family> the name of the asset family it belongs to.
  Due to the behavior of Akeneo API, you have to indicate the name of the asset family to get the asset media file.
• For instance: https://my-company-akeneo.twic.pics/asset/<asset family>/<media code> could be https://my-company-akeneo.twic.pics/asset/deco/DECO_TEXTILE_CURTAIN_WHITE_300152243027.

By reference entities or records media files

Available for Akeneo Enterprise Editions only.

• Endpoint: /reference-entity/<media code> with <media code> being the code of the media file associated to a reference entity or a record.
• For instance: https://my-company-akeneo.twic.pics/reference-entity/<media code> could be https://my-company-akeneo.twic.pics/reference-entity/color200.

The example below shows a PIM image integration with TwicPics Native:

<img
  data-twic-src="image:media/5/9/z/2/43z8b1586_DEMO_IMAGE.jpg"
  alt="Demo image"
/>

Here the example makes use of TwicPics API to integrate the PIM image:

<img
  src="https://my-company-akeneo.twic.pics/media/5/9/z/2/43z8b1586_DEMO_IMAGE.jpg?twic=v1/cover=16:9/resize=600"
  alt="Demo image"
/>

Select specific assets media files

The assets media files endpoint can actually feature multiple images. By default, the TwicPics Akeneo Connector will use the first one following the order in which the Akeneo API itself sent them.

You can override this behaviour in two ways:

• using indexing
• using filtering

Indexing

Let's consider the asset located at https://my-company-akeneo.twic.pics/asset/cloth/dress and let's suppose that there are at least three images associated to it.

You can retrieve the third image by adding its index at the end of the URL like so:

https://my-company-akeneo.twic.pics/asset/cloth/dress/2 (notice the /2 at the end)

Indexes are zero-based, thus to get the first element, you have to use index 0 and to get the third element, you have to use index 2.

If the asset only features two images, then the TwicPics Akeneo Connector will simply circle back. So, in that instance, the three following URLs would be strictly equivalent:

• https://my-company-akeneo.twic.pics/asset/cloth/dress/2
• https://my-company-akeneo.twic.pics/asset/cloth/dress/0
• https://my-company-akeneo.twic.pics/asset/cloth/dress

Filtering

While indexing can be useful, it can prove more effective to filter images based on associated values.

Many asset media are localized and this information is usually stored in the Akeneo API as a locale value attached to each image. You can add a filtering condition at the end of the URL to select language-specific images.

For instance:

https://my-company-akeneo.twic.pics/asset/cloth/dress/locale=en_US

would retrieve the american english images associated with the asset.

If there happen to be several such images, you can use indexing to select a specific one like so:

https://my-company-akeneo.twic.pics/asset/cloth/dress/locale=en_US/1

But what happens if you don't have a locale=en_US image? The TwicPics Akeneo Connector would return a 404 response. Thankfully, you can chain filters so that each subsequent filter acts as a fallback.

Let's take the following example:

https://my-company-akeneo.twic.pics/asset/cloth/dress/locale=en_US/locale=fr_FR/locale=null.

This will deliver:

• the first american english image if there is any
• failing that, the first french image if there is any
• failing that, the first non-language specific image is there is any

Furthermore, filters can contain complex logical expressions using parenthesis and logical operators & and |.

For instance, supposing you have a color value associated to your images, you could write filters of the form:

• locale=en_US&color=blue
• or (locale=en_US|locale=fr_FR)&color=blue

Finally, the special filter true can be useful as a "whatever is there" kind of fallback.

For instance, locale=en_US&color=blue/true would return the american english, blue colored images if they exist or whatever is there otherwise.

Support service

For any issue related to the Image Optimization Akeneo Connector for TwicPics, please contact the support team by sending an email at support@twic.pics.

Check out our Service Level Agreement to get more information about our different services.