# Overview [**Pixboost**](https://pixboost.com/) is an Image CDN Cloud Service that delivers images end to end for your website or application. The service works end-2-end and includes 2 main components: * API - Collection of HTTP endpoints that optimising and transform images * CDN - Content Delivery Network that stores optimised images in the closest to the user location Once an image has been processed, it's cached on CDN, increasing the speed at which images can be retrieved on subsequent requests. ![Diagram that shows how Pixboost Image CDN works](/files/-MeXpLXdhPQMs-ZDm_uI) Here is the short video on how to use Pixboost API: {% embed url="" %} In the next chapter, you'll learn how to start using Image CDN in five simple steps. # Quickstart We try to make the start with Pixboost as fast and as easy as possible. We aim it to be under 10 minutes. So, lets cut it short. The main goal is to setup images on your websites to be served through the Pixboost. ![Diagram of how Pixboost serves images](/files/-MeXpLXdhPQMs-ZDm_uI) ## Step 1 - Signup [Signup](https://pixboost.com/customer/#/signup) using your Google account or by filling in the details. ![Signup form](/files/CnzxXbYnIoRjyq541nGH) If you decided to go with Email/Password then you'll receive a confirmation email shortly after submitting the form. ## Step 2 - Setup source images Add at least one **Image Domain** or **Image Source**. This will let the service know where the destination of you source (original) images. Image source is preferred way, because your image URLs will be shorter when using in the HTML markup. However, Image Domain is easier to setup. * For Image Domain simply click `+` button and fill in the domain name ![Adding a new domain with source images](/files/kNcOK8S4tTcr2oiogGmB) * To create HTTP Image Source click on `bucket` button ![Adding HTTP source](/files/7aDDY9l8ZdlPmE2Amspf) ## Step 3 - API key Once you added a domain or source you will see the Dashboard main view. We have already generated an API key for you, so you can start optimise your images. ![List of API keys in dashboard](/files/ENs64Ww6wY3OZCpb2TLT) ## Step 4 - Call API Use API to optimise or resize the image from your website. You can use Chrome to call the API * If you used domain in the [Step 2](#step-2) then your URL would look like `https://pixboost.com/api/2/img/[SOURCE IMAGE URL]/[OPERATION]?auth=[API KEY]&[OPERATION OPTIONS]` ![Example of optimising the image using domain](/files/qxXQGI7ZcIBOBeUFYMUs) * If you used HTTP (or other) image source `https://pixboost.com/api/2/img/[SOURCE ALIAS]/[RELATIVE TO ALIAS PATH]/[OPERATION]?auth=[API KEY]&[OPERATION OPTIONS]` ![Example of optimising the image using HTTP source](/files/Ls1suxGNSPmzAPNpIJKp) ## Step 5 - Optimise the image on the website Update image URL in the markup of your website ![Use image in the HTML markup](/files/7F8zIBb9DgVTQW7fXWWy) ## What's next * Learn more on how tou use Pixboost [API](/api) * Managing [API keys](/setup/manage-api-keys) * Setup [custom domain name](/setup/custom-domain) # Tools and Setup There is only one step that you need to do to start using Pixboost - [add at least one image domain](/setup/source-images/domain) or image source. You will already have one active API key that you can use, but [you can add more or rotate them](/setup/manage-api-keys) in case you have different projects and don't want to have all eggs in one basket. It's a good security practice separating you API keys. ## [Adding Images Domain](/setup/source-images/domain) ## [Adding HTTP Image Source](/setup/source-images/http) ## [Adding AWS S3 Bucket Image Source](/setup/source-images/s3) ## [Managing API Keys](/setup/manage-api-keys) ## [Managing API secrets](/setup/api-secrets) ## [Managing Users](/setup/manage-users) ## [Custom Domain Name Support](/setup/custom-domain) ## [Cache Invalidation](/setup/cache-invalidation) ## [Snippet Generator](/setup/snippet-generator) # Source Images # Adding Source Image Domain **Image domain** is the domain name of your server where your images are stored. Pixboost will allow only requests to the images from domains that are listed. Using list of domains allows us to make service secure and protect you account from malicious abuse. When you login for the first time then you will see a "Welcome" banner: ![](/files/-Lmt8zq_iKby7-T50XuA) Click on the "Plus" button, and you will have to add your domain name in a dialog window "Add domain": ![](/files/-Lmt8zqbogVB_zZi2m2G) {% hint style="info" %} If you'd like to load images from a private AWS S3 bucket then click on the "Bucket" icon and follow [steps from here](https://github.com/Pixboost/docs/blob/main/setup/source-images/adding-s3-bucket-image-source.md) {% endhint %} Enter your domain and click the "Add" button: ![](/files/-Lmt8zqdM9jQtiCA-8-N) You will see adeed domain in the list now: ![](/files/-Lmt8zqfDlVBtCigpCxS) That's enough to start using the service. Try it out it in your browser: ``` https://pixboost.com/api/2/img/http://i.imgur.com/RgSMqlKg.jpg/resize?size=200&auth=MzI0NTc5NDAyMQ__ ``` If you prefer to not specify full URL of the original image # Adding HTTP Image Source You could add HTTP image source to shorten URLs that you are using for the integration. ![](/files/-MeZwlsAPh02f8qx3irO) ## Adding a new source * [Login](https://pixboost.com/customer/#login) to your Pixboost account. * Click on "Add source" link under the "Images Sources" panel ![](/files/-M49Z5aXifDO3PTcL0hU) * In the appeared form set Type to "HTTP" and fill in the details * *Alias* is a unique identifier of the images source that will be used in the URL when calling API * *Images location* is a URL where the original images stored ![](/files/-MeZwlsB4f-yPmQrsK7G) * Click on "Add" button and verify that the source has been created ![](/files/-MeZwlsCIB9-_2_dlWDX) # Adding AWS S3 Bucket Image Source Using Pixboost, you can set up a private S3 bucket to be a source of your images. Here, we will go through requirements for the S3 bucket, how to add an integration to Pixboost and how to optimise images from the bucket using API. ## AWS setup We assume that you already have S3 bucket with your images stored there. If not then you can read how to do that [here](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html). To setup a new user that you'll integrate with Pixboost: * Create a new [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) * [Add new credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for the user. * [Update or create bucket policy](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-bucket-policy.html) and give the user s3:ListBucket and s3:GetObject permissions. Below is an example of a bucket policy: ```javascript { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::user/" }, "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::" }, { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam:::user/" }, "Action": "s3:GetObject", "Resource": "arn:aws:s3:::/*" } ] } ``` ## Pixboost setup To set up the integration: * [Login](https://pixboost.com/customer/#login) to your Pixboost account. * Click on "Add source" link under the "Images Sources" panel ![](/files/-M49Z5aXifDO3PTcL0hU) * In the appeared form set Type to "Amazon AWS S3 Bucket" and fill in the details * *Alias* is a unique identifier of the images source that will be used in the URL when calling API * *Bucket name* is the name of a bucket * *Region* is an AWS region ID of the bucket * *Path Prefix* is an optional prefix that will be used for all requests. It could be used if all your images in the bucket stored in one folder. In that case, you could set "Path prefix", and you won't need to add it to each API call. * *Access Key* is an AWS IAM user's access key created in the step above * *Secret Key* is an AWS IAM user's secret key created in the step above ![](/files/-M49Z5aZAAPyG4ZfM2CZ) * Click on "Add" button and verify that the source has been created ![](/files/-M49Z5aaCKindXmUagM_) ## Using API All API requests follow the [original pattern](https://github.com/Pixboost/docs/blob/main/setup/api/README.md): `https://pixboost.com/api/2/img/[ALIAS]/[PATH_TO_THE_IMAGE]/[OPERATION]?[OPERATION_PARAMS]&auth=[API_KEY]` Let's consider a configuration from the step above. For instance, if there is an image in S3 bucket with a path (key): `prefix/another-prefix/images/hello.png` then to resize it we use the following API call: `https://pixboost.com/api/2/img/bucket/images/hello.png/resize?size=200&auth=[API_KEY]` In the example above `/bucket` (after `/api/2/img`) will be replaced with bucket name and path prefix - `pixboost-test-source/prefix/another-prefix` ## Limitations You could have a maximum of 10 images sources. That is a soft limit, so if you'd like to raise it, please email us at # Managing API Keys **API Key** is a string that is used to access API and identify requests to your Pixboost account. API Keys are globally unique. Once you signed up you have one API key that you can see in the dashboard: ![](/files/74UulsxXIJvVIgwJQiV5) ## Usage You'll need to pass an API Key in a query parameter called "**auth**" in the transformation URL. For example: To use the API key add it as a value in the "auth" query parameter when using API: > Be careful when **deleting** API keys. Any API requests that use deleted keys will be failing. ## Labels You can create new API Keys from the dashboard and add a label to them, so you remember what you use each key for. Labels are only used for information and reporting purposes. Some useful examples of the label could include a website and environment. For instance: * dev * test-site-1 * prod-site-2 ## Security API keys are not secrets and are shared publicly when used to access API. When passing an API key with a request, the service can link the request to an account, therefore limiting the source image destination to image sources/domains you specified. ## Limits There is a soft limit of 10 API keys per account. If you need more - please contact [support](mailto:customer.service@pixboost.com). # API Secrets API secrets are used to call [workflows](/setup) API. You can manage your API secrets from the dashboard: ![](/files/-LmtPzPoVTI2-W6A7423) Please, be aware that we are not storing secrets in plain text, so you should copy it once created and store it securely on your side. You should not disclose your secret, and if it's compromised, then we recommend deleting it and creating a new one. # Managing Users You can have multiple users in one Pixboost account. That enables you to minimize the risk of loosing access to the account and do not rely on one login. Moreover, you can set up the permissions of each user using predefined roles. Currently, there are three roles you can pick from: * Super Admin - have full access to the account. Only Super Admin can manage users * Web Developer - have access to image CDN setup including image sources, API keys, secrets, and analytics * Billing Admin - have access to payment methods, billing, and analytics ## Adding a new User * Login to the dashboard and go to the "Users" menu item under the "Account" section ![](/files/Ymf4BbMfagTOE5vFm2vo) * Click on the "Invite New User" button * Fill in the Email and pick a role ![](/files/5qrEhYEx3zWVmMAiEAhL) * Click the "Add" button * User will receive an invitation email shortly after that with the setup link ## Good practices It's usually a good practice to have at least 2 Super Admins, so there is no dependency on a single person/mailbox. Giving the finance department access using a "Billing Admin" role could help them monitor spending, and update payment details in time without the involvement of the IT department. ## Limitations The maximum number of users in the account is set by your current plan and can be looked up on the ["Prices" page](https://pixboost.com/prices/). Every account must have at least one "Super Admin" user. # Snippet Generator **Snippet Generator** is a Tool that helps users to quick start with Pixboost and to make the setup much easier. It creates the small blocks of reusable code to insert in a code of a website. It is available for all registered users of our service. ![](/files/-Lmt8zQ2DimRyM-yM4em) To start using Pixboost all you need is to modify the URLs of images that you would like to pass through the service for optimization for scaling purposes. That's exactly what Snippet Generator will do for you. ## How to use it from a sandbox or from the app To start using Snippet Generator you have two options. You either use our demo account to check it out or you log into your Pixboost account and there you can use this tool for your projects. For sandbox follow the link to [start Snippet Generator](https://pixboost.com/snippet/?k=MTg4MjMxMzM3MA__) * Paste URL to the image you would like to compress, scale and deliver through CDN. Or you can use our example image to see how this tool works. Pre-Set Image URL - `http://www.midday.coffee/image.jpg` As a sandbox user or as a registered user you use the Snippet Generator in a similar way: * Press **Generate** button to generate a snippet. ![](/files/-Lmt8zQ8P1l94CMlIt8t) * Select **Responsive** or **static** setting. In a responsive setting you can set sizes for each type of the device you would like to support; computer, tablet or mobile. * Select **Lazy Loading** option if you would like to turn on lazy loading for your image. * Enter **ALT Text** for the image. This text will show up in the code of your snippet. * Set up an image for each of the devices in the following way: * Input **weight** and/or **height** according to your website needs. These options are available if the **as-is** setting or **hide** setting are not activated * Select the **As-is** setting if you would like to leave your image as it is. This option would be helpful if you want to deliver an image through CDN without changing it. Other settings will be deactivated. * Select the **Hide** setting if you would like to hide this image on this type of device. Other settings will be deactivated. ![](/files/-Lmt8zQAY8xfVtZLG8fN) * You can preview your images for devices and make changes if needed. ![](/files/-Lmt8zQCgxXI3HlyUJZp) * Finally, after you are happy with your setup, you can **Copy** snippet and paste directly into your website code. ![](/files/-Lmt8zQEUwUPbbOL-Vex) If you think that this tool can be improved please don’t hesitate to tell us in what way we can improve it and make it more useful for you. # Custom Domain Name By default, API is accessible on pixboost.com domain, but you can easily use your own. It just 3 simple steps: * Create a new DNS record for the subdomain. For instance, to use ***static.foo.com*** domain you will need the following DNS record: | Type | Subdomain | Canonical Name | | ----- | --------- | -------------- | | CNAME | static | pixboost.com. | DNS changes can take some time to apply. You can test DNS change by loading subdomain in the browser. Enter static.foo.com in the location bar and you should see pixboost website. * Write us an email on ****, so we could issue a SSL certificate for a new domain. * You can start accessing API on ***static.foo.com*** instead of ***pixboost.com.*** Once SSL certificate and DNS change is done # Cache Invalidation Cache invalidation is a function that helps you to remove image from the CDN. You can delete images using either * URL of the original image * Path to the image that starts with the [Image Source](/setup/source-images/http) alias ![](/files/mWGz1TF23IV5VUXWAjGU) ## Limitations Invalidation is intended for use in exceptional circumstances, not as part of your normal workflow. Invalidations don't affect cached copies in web browser caches or caches operated by third-party internet service providers. Invalidations are rate-limited. You can submit at most one invalidation per minute. # HTTP/2 Support Pixboost automatically supports HTTP/2 protocol. If the [browser supports HTTP/2](https://caniuse.com/#search=http%2F2) protocol, we deliver it accordingly. HTTP/2 was created to improve efficiency of the existed HTTP protocol by including several features: * it is binary, instead of textual * is fully multiplexed, instead of ordered and blocking * can therefore use one connection for parallelism * uses header compression to reduce overhead * allows servers to “push” responses proactively into client caches This all makes it easier to deliver fast and efficient website. More on HTTP/2 protocol please read it's [official page](https://http2.github.io/). # HTTP/3 Support Pixboost automatically supports HTTP/3 protocol. HTTP/3 was created to improve efficiency of the existed HTTP protocol by including several features: * HTTP/3 has better earlier data support * HTTP/3 has much faster handshakes * HTTP/3 does not exist in an insecure or unencrypted version. This all makes it easier to deliver fast and efficient website. More on HTTP/3 protocol please read it's [official page](https://http3.net). # API. URL-based integration To make integration easier we provide a lightweight API that you can directly use from HTML code. ## URL pattern for API call All endpoints follow the same pattern `https://pixboost.com/api/2/img/[IMAGE_URL|IMAGES_SOURCE_ALIAS_WITH_PATH]/[OPERATION]?[OPERATION_PARAMS]&auth=[API_KEY]` | Item | Description | | ---------------------------------------- | ------------------------------------------------------------------------- | | **\[IMAGE\_URL]** | The URL of the original image you would like to process through Pixboost. | | **\[IMAGES\_SOURCE\_ALIAS\_WITH\_PATH]** | An alias of an images source with relative path to the image. | | **\[OPERATION]** | Pixboost function call | | **\[OPERATION\_PARAMS]** | Operation parameters for a function call you are using | | **\[API\_KEY]** | A unique [API key](/setup/manage-api-keys) | ### Example using **\** tag Before: `Midday Coffee` After: `Midday Coffee` ### Example using **\** tag Before: ```markup ``` After: ```markup ``` We support all transformation required for the typical website. ![](/files/-Lmt8zRYV7T0MqqVegRb) Read more on operations: ## [Resize](/api/resize) ## [Fit](/api/fit) ## [Optimise](/api/optimise) ## [As is](/api/as-is) You can explore API sandbox here: # Resize API endpoint - `/api/2/img/[IMAGE-URL]/resize?size=[NEW-SIZE]` ## Description **Resize** - resizes image with preserving aspect ratio and optimizes it using lossy compression. If you need the exact size then use fit operation. ## Parameters **size** (**required**) - new size (in pixels) of the image in the format `WIDTH and xHEIGHT`. You can specify only one dimension and the second will be calculated according to the image's aspect ratio. **dppx** (optional) - Number of dots per pixel defines the ratio between device and CSS pixels. The query parameter is a hint that enables extra optimisations for high density screens. The format is a float number in the same format as window\.devicePixelRatio. **trim-border**(optional) - Will remove the edges of the image with the same color, if the option specified. ### Examples * `size=200` - resize to 200 px wide preserving aspect ratio * `size=x80` - resize to 80 px high preserving aspect ratio * `dppx=2` - sending a hint to the API that screen has DPI=2 | Parameters | Image | | --------------------- | :-------------------------------------------------------------------------------------------------------------------------------: | | Original | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | | size=200 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/resize?size=200\&auth=MTA0ODU5NDA0NQ__) | | size=x80 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/resize?size=x80\&auth=MTA0ODU5NDA0NQ__) | | size=200\&dppx=2 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/resize?size=200\&dppx=2\&auth=MTA0ODU5NDA0NQ__) | | Original | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | | size=200 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/resize?size=200\&auth=MTA0ODU5NDA0NQ__) | | size=200\&trim-border | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/resize?size=200\&trim-border\&auth=MTA0ODU5NDA0NQ__) | **You can inspect URLs and sizes of the examples by "right-click -> Copy Image address"** # Fit API endpoint - `/api/2/img/[IMAGE-URL]/fit?size=[NEW-SIZE]` ## Description **Fit** - resizes, crops, and optimises source image. This operation does not respect original aspect ratio. If you need to preserve aspect ratio then use [resize operation](/api/resize). ## Parameters **size** (**required**) - new size (in pixels) of the image in the format `WIDTHxHEIGHT`. You have to specify **both** dimensions width and height. **dppx** (optional) - Number of dots per pixel defines the ratio between device and CSS pixels. The query parameter is a hint that enables extra optimisations for high density screens. The format is a float number in the same format as window\.devicePixelRatio. **trim-border**(optional) - Will remove the edges of the image with the same color, if the option specified. ### Examples * `size=200x100` - scaling by the smaller side which is height, cropping sides, center positioning * `dppx=2` - sending a hint to the API that screen has DPI=2 | Parameters | Image | | ------------------------- | :--------------------------------------------------------------------------------------------------------------------------------: | | Original | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | | size=200x100 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/fit?size=200x100\&auth=MTA0ODU5NDA0NQ__) | | size=200x100\&dppx=2 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/fit?size=200x100\&dppx=2\&auth=MTA0ODU5NDA0NQ__) | | Original | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | | size=200x200\&trim-border | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/fit?size=200x200\&trim-border\&auth=MTA0ODU5NDA0NQ__) | | size=200x200 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/fit?size=200x200\&auth=MTA0ODU5NDA0NQ__) | **You can see URL of the examples by "right-click -> Copy Image address"** # Optimise API endpoint - `/api/2/img/[IMAGE-URL]/optimise` ## Description **Optimise** - optimises images using lossy compression automatically. ## Parameters **dppx** (optional) - Number of dots per pixel defines the ratio between device and CSS pixels. The query parameter is a hint that enables extra optimisations for high density screens. The format is a float number in the same format as window\.devicePixelRatio. **trim-border**(optional) - Will remove the edges of the image with the same color, if the option specified. ### Examples * `dppx=2` - sending a hint to the API that screen has DPI=2 | Parameters | Image | | ------------- | :-----------------------------------------------------------------------------------------------------------------------: | | Original | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | | No parameters | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/optimise?auth=MTA0ODU5NDA0NQ__) | | dppx=2 | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/optimise?dppx=2\&auth=MTA0ODU5NDA0NQ__) | | Original | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | | trim-border | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/optimise?trim-border\&auth=MTA0ODU5NDA0NQ__) | **You can see URL of the examples by "right-click -> Copy Image address"** # As is API endpoint - `/api/2/img/[IMAGE-URL]/asis` ## Description **Asis** - does not perform any transformations. Respond with the original image without any modifications. Would be useful to leverage CDN. ## Parameters No parameters are required. ### Examples | Original Image | Image after Pixboost transformation | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | ![](https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__) | ### Sandbox | Original Image | Image after Pixboost transformation | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [www.midday.coffee/assets/cup.jpeg](https://github.com/Pixboost/docs/tree/8f93cdfa3e5fdb7584ce488ef51153268bef537f/api/www.midday.coffee/assets/cup.jpeg) | [https://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/fit?size=200x100\&auth=MTA0ODU5NDA0NQ\_\_](http://pixboost.com/api/2/img/https://pixboost.com/img/demos/tshirt.jpg/asis?auth=MTA0ODU5NDA0NQ__)\_ | # Using with React You can use pixboost-react library for an easy integration with React application. The library work well with other frameworks that using React, e.g. Next.JS. Please follow the link to the [GitHub page](https://github.com/Pixboost/pixboost-react) to read full documentation. # Shopify Integration You can use Pixboost Image CDN on your Shopify by: * Using one of our [themes](#themes). No coding skills required. * [Integrate your custom theme with Pixboost](#integration-with-a-custom-theme). ## Themes We integrated Pixboost with below themes: * [Debut](https://github.com/Pixboost/shopify-wroom-wroom-debut) Please, follow steps from ["Installation"](#installation) section to use them on your store. ## Installation * Follow the theme link from the [Themes](#themes) section * Go to "Releases" page and download a zip archive with the latest release ![](/files/-LvDAUIvAxJs7tKKyrLa) * Open your Shopify store dashboard and go to the "Themes" section ![](/files/-LvDAUIxbT3u4I_2bnQv) * Click on "Upload theme" button and select the zip archive that you downloaded before ![](/files/-LvDAUIzAN17ZpF4cm2i) * An uploaded theme should appear on the list ![](/files/-LvDAUJ0Q0d3FO0iFRqC) At this point, you should be able to preview the theme, and it will use Pixboost demo account. All the images will be served from Pixboost Image CDN. Note that first time the images will load slowly as they will go through optimisation and CDN uploading process. Reload the page after the initial load to see the real performance. ![](/files/-LvDAUJ2xZleVdiG1_TS) Once you are happy with the result, you would need to create a Pixboost account and use your API key: * [Sign up here](https://github.com/Pixboost/docs/tree/f5010c234fd24fe5e3402831d8152bbad3b3c3ea/shopify/pixboost.com/customer/README.md#/signup) and select Shopify integration ![](/files/-LvDAUJ4YUkbGjNHBpHO) * Confirm your email and copy your API key from the dashboard ![](/files/-LvDAUJ63Ulzw6Hz_AQy) * Go back to your Shopify store and click on "Customize" button on the uploaded theme ![](/files/-LvDAUJ8yGjAlYrZag9d) * Open "Theme Settings" tab and go to "Pixboost" section ![](/files/-LvDAUJAb0S2eN-b_k9j) * Paste or enter your API key ![](/files/-LvDAUJCjzGihShxR6Bx) * Click "Save" button and preview the theme to make sure that images are working ![](/files/-LvDAUJExfUJdcF9xmFx) Congratulation! You now have responsive, optimised and fast images on your Shopify store. Keep customizing your page layouts and publish the theme once you are ready. ## Integration with a custom theme To integrate your theme with Pixboost requires modifications in the code of the theme. Please, do not hesitate to reach us on , so we can help you with integration. We tried to make the process easy and wrote [a step by step guide](https://medium.com/pixboost/boosting-image-performance-of-your-shopify-store-d3696ac71f93?source=pixboost-help) # Automated Workflows Workflows help you to automate certain tasks while managing your images using Pixboost service. Workflows consist of API endpoints that you could use from your applications. Currently, Pixboost supports the following endpoints: * [Cache Invalidation](/workflows/cache-invalidation) * [Warmup](/workflows/warmup) To call a workflow API, you will need to create an API secret first. Please read about creating and managing API secrets [here](/setup/api-secrets). An example of the workflow could be a CDN cache invalidation when a source image is updated. You can find a reference implementation of such a scenario [here](https://github.com/Pixboost/aws-s3-invalidate-cdn) ![](/files/-LmtPzRTu4vV6OkKuqBJ) ## Pricing There are a number of calls that you allowed to do on each billing plan. Please refer to the [pricing page](https://pixboost.com/prices/) to see the exact numbers. # Cache Invalidation API endpoint - `DELETE /api/2/img/[IMAGE-URL]?auth=[API_SECRET]` ## Description Cache invalidation invalidates images cached on CDN and Pixboost 2nd level cache. Example: ```bash curl -X DELETE 'https://pixboost.com/api/2/img/http://www.midday.coffee/banner.jpeg?auth=ABCDEF' ``` ## Parameters API\_SECRET - [secret key](/setup/api-secrets). ## Response 200 - Image has been invalidated. 202 - Invalidation process began and will finish soon. Usually it will take up to the 5 minutes. 401 - Failed authorization. Image domain is not in the list of [images sources](/setup/source-images/domain) ## Example You can find reference example of using cache invalidation workflow with S3 bucket [here](https://github.com/Pixboost/aws-s3-invalidate-cdn). ## Limitations Please, be aware that invalidations don't affect cached copies in web browser caches or caches operated by third-party Internet service providers. In most cases, using versioning on file names is a better option. # Warmup API endpoint - `POST /api/2/img/warmup?auth=[API_SECRET]` ## Description /warmup performs transformations and caches them, so it will speed up the first response time from the real user. The typical usecase is an application where the user can upload images by themselves, then see them once uploaded. The first render could take some time (1-4 seconds) and using `/warmup` will decrease the response time. ![](/files/-MhWDuRo2IqpGZF6a7qd) The below example will warm up caches for 2 variants of the image: * `https://pixboost.com/api/2/img/http://www.midday.coffee/banner.jpeg/resize?size=x100&auth=ABCDEF` * `https://pixboost.com/api/2/img/http://www.midday.coffee/banner.jpeg/resize?fit=100x100\&auth=ABCDEF` The URLs of the images to warm up should be exact the same as you use in your front end implementation. ```bash curl -X POST -H 'Content-Type: application/json' \ 'https://pixboost.com/api/2/img/warmup?auth=ABCDEF' \ -d '{"images: ["https://pixboost.com/api/2/img/http://www.midday.coffee/banner.jpeg/resize?size=x100&auth=ABCDEF","https://pixboost.com/api/2/img/http://www.midday.coffee/banner.jpeg/resize?fit=100x100&auth=ABCDEF"]}' ``` ## Parameters API\_SECRET - [secret key](/setup/api-secrets). ## Response 202 - The warmup has been successfully initiated. ## Example You can find reference example of using cache invalidation workflow with S3 bucket [here](https://github.com/Pixboost/aws-s3-invalidate-cdn). You can replace cache invalidation call with `/warmup` in Lambda. ## Limitations Maximum number of images to warmup in one call is 20. This is a soft limit and could be increased on request. # Performance Testing If you take a closer look at some leading online shops or web portals like real estate or online news websites, you could easily notice that images take up to one half of total transferred Internet traffic. Web developers work mostly on improving JS/CSS performance. But what about static content like images? Thinking of it I came up with the idea to find a way to measure performance of images on a website. To demonstrate this method, I have created a [demo site](http://www.midday.coffee/original/cups.html) that looks like a typical listing page on an online shop. Sources of the website are publicly available on [github](https://github.com/Pixboost/midday-coffee). You are welcome to play with it as much as you want. After that you can apply your knowledge to your own website or page. So, lets move on to the fun stuff. ## Performance Testing best practices Before we dive into measurements let’s iterate through some common rules that are relevant for any performance testing: * **Always do multiple measurements (more than 2).** It’s important to make sure that data you collected are consistent. If you can see a major gap between measurements then something is not right, and therefore, you need to investigate a cause and repeat a test. * **Conditions of the tests must be the same.** Every time you are running tests make sure nothing changing externally. Some examples of external conditions could be the Internet speed, load of test server, etc. * **Keep source data of load tests.** If your input data is based on the end figures you are computing then it’s better to save source files as well. It might become important if you realize that your calculations are wrong or there is a missing metric. * **Create test report.** At the end of your tests you should have a report that you can store along with source data. That’s what you can use to compare results. * **Run tests regularly.** Performance testing shouldn’t be one time thing. Ideally you will want to run them on every change or on every release. ## Tools In performance testing methodology is usually goes hand by hand with the tools. Sometimes those tools can be very expensive. But I will show you how to measure performance thoroughly and efficiently using open source tools and free apps. So, that set of tool covers all our needs for today: * Chrome Dev Tools * HAR * JQ ### **Google Chrome Dev Tools** Our main tool would be**Google Chrome**which has some powerful developer features that can tell us a lot about what is going on. The network tab will be our best companion today. To enable it press**F12**in Google Chrome and click on “**Network**” tab. ![](https://cdn-images-1.medium.com/max/2000/1*WU2-ZTBZZtvHfFhO7j6mJw.png) Here we can see all network requests that have been done during the website load. We can get a lot of useful information for us, such as name of the file, size of the HTTP response and time that it take to load. So, we can collect all this information and analyze it. ### Export to HAR feature But instead of do it manually we can use another feature of Google Chrome Dev Tools — **export to** [**HAR**](https://en.wikipedia.org/wiki/.har): ![](https://cdn-images-1.medium.com/max/800/0*389TKz6JI6nydlHH.) HAR stands for “HTTP Archive Format” and describes HTTP requests and responses using JSON format. Below is one record from our requests (I removed some headers to make it shorter): As you can see it provides very comprehensive set of data about the request. We can find URL of the image, all the headers and what is the most interesting for us — timings. Those HAR files are quite big and we don’t want to analyze them manually either. ### JQ command line tool That’s where[**JQ**](https://stedolan.github.io/jq/)comes into a game. JQ is a command line tool that can process JSON files using special filters. It’s quite powerful and complex in the same time. For instance, if we want to print all images that has been loaded then we would write this in command line: Let’s see what we are doing here. \_.log.entries\[]\_is a selector that will pick every object from “entries” array and pass it down the pipe (|). \_{“url”: .request.url }\_will create a new object for every array entry and will contain only URL os the request. \_select(.url | match(“png|jpg|PNG|JPG|jpeg|JPEG”)\_will filter images out of all requests ## Setting up tests Let’s see how we address all the requirements described above: * We will do 3 measurements and make sure that deviation is not huge. * Setup network throttling in Chrome Dev Tools, so that our tests won’t depend on the Internet speed. ![](https://cdn-images-1.medium.com/max/800/0*lPi0nEx92fC0t_vU.) * Disable caching. We can also do this in Chrome Dev Tools: ![](https://cdn-images-1.medium.com/max/800/0*CO5Wlnp4qjHy76XL.) * Make measurements on 3 visual breakpoints: desktop, mobile and tablet * Store all our measurements in a table that we will push to the repo with sources. A report will include all metrics, date and other parameters like visual breakpoint/device. * Store all HAR files along with the report. ## Metrics Now, when we have a source data and tools we can do actual testing. We are ready to**define our metrics**. When dealing with web sites or applications the natural feeling is always to measure page load time. In fact it won’t give us accurate statistic data about images at all because certain factors can influence page load time: * DOM * Javascript/CSS scripts * 3rd party analytics or marketing scripts * On page script execution. Instead of using generic metrics let’s think of metrics that will only be related to images and won’t be affected by anything else. I have spent some time thinking and trying different approaches, and here are the list of metrics that I came up with: * **Number of images on the page.** By using this number you can track how many images are loaded on the page. * **Total transferred size of images.** This is a number of bytes that had been downloaded. It’s a good metric, and in most cases it can be improved really well by optimizing images or giving them a correct size (resizing or cropping). * **Time taken for all images to load.** This one shows us how long it takes for all images to load. It doesn’t take into account the fact that images load in parallel, but just if they would load sequentially. This metric also exclude queuing time that browser been waiting to start loading a resource. * **Total time with queuing** . This is the same as above but including queue time. Queue time can be reduced by using some techniques, for example, you can move all your assets to separate domain, so that browser can use different thread pool for loading your images. ## Let’s Do It I prepared**some**(what scripts, define please!)JQ scripts that we will be using. I added them to[github repo](https://github.com/Pixboost/har-jq-cheatsheet)for your convenience. They also could be easily modified in case you want to measure performance of other resources like JS/CSS. There is a bash script that you can run by passing HAR file. It will print the statistic for all images. Firstly, let’s load the[web page](http://www.midday.coffee/original/cups.html)3 times and save HAR files. Then run har-stat.sh script 3 times to get the results: Then let’s put results into the report: Now let’s change device to IPhone 7 and run the same tests. We can change device in Chrome Dev Tools: ![](https://cdn-images-1.medium.com/max/800/0*YceaUd_jGzHM_2d2.) Let’s capture values again: Finally, we need to measure for tablet as well. At the end I put all source files and report into[git repo](https://github.com/Pixboost/midday-coffee/tree/master/performance-testing/original/cups/23-03-2018). Once we published our report we can think of the test as done! ## Improving Images And I’ll tell you how we can do this in the next article :) ## Conclusion I hope this would be useful for you, so that you could see some real numbers before and after optimization. There are many manual steps in the process and I’m currently working on automating them all by running headless Google Chrome in the Docker. Feel free to contribute to a[git branch](https://github.com/Pixboost/har-jq-cheatsheet/tree/feature/docker-and-script). # Open Source Version Pixboost image manipulation service sources are accessible for public on [github](https://github.com/Pixboost/transformimgs). We believe that **open source** is the most efficient model of software development. Also, it allows our customers to deploy service into their own data centres. We are always happy to provide consulting services to customize the solution for your needs.