TwicPics Domains
Upon creating your account, your very own TwicPics domain is available. All your image interactions will now be made through it and you will be able to attach as many image sources as you want using our powerful path system.
Single Domain
Pay-As-You-Go customers get a unique, auto-generated subdomain. Pro customers can create organizations encompassing multiple subdomains whose names they can choose. Enterprise customers can even go beyond subdomains and use their own domain names if they so desire.
As an introduction to TwicPics, a single domain is plenty enough given you are not limited to a single source of images per domain. We will explore the advantages of multiple domains later on in this documentation nonetheless.
Single Path
A TwicPics domain is, simply put, a collection of paths that each reference a folder online.
The simplest possible configuration is to have the root of your domain (/
) pointing to the root of your media server.
For instance, if the root of <sub>.twic.pics
points to https://media.my-company.com/
then https://<sub>.twic.pics/my-image.png
will point to https://media.my-company.com/my-image.png
.
Passing through the TwicPics domain has the following advantages:
- the image is optimized right away: WebP will be delivered to browsers that support the format, users with a bad connection will get a lighter image, etc
- the image will be delivered through the TwicPics CDN, reducing latency and removing pressure on your own media server
- the image can now be transformed using the TwicPics URL API
- the actual location of the image is private, only TwicPics knows where it is located
- you can further protect your images using source authentication and/or default manipulations
- crucially, you decide and control where your images are stored and you are free to move them wherever your want without breaking your website, provided you update your TwicPics domain configuration in a timely fashion
Furthermore, even if TwicPics only recognizes AVIF, GIF, HEIF, JPEG, PNG and WebP files as transformable images, other files will pass through, unaltered.
Multiple Paths
What if your images are spread on several servers?
While it is quite common for most assets to be stored on a media server (say https://media.my-company.com/
), some are still usually kept on the same server as the website (say https://www.my-company.com/
).
Thankfully, the solution is as simple as creating two paths on the same domain!
One possible configuration would be:
path | source images URL |
---|---|
/media | https://media.my-company.com/ |
/web | https://www.my-company.com/ |
which would make it so:
https://<sub>.twic.pics/media/logo.png
points tohttps://media.my-company.com/logo.png
https://<sub>.twic.pics/web/banner.png
points tohttps://www.my-company.com/banner.png
If you are using the TwicPics Script, then:
- a
data-twic-src
referencingimage:media/logo.png
points tohttps://media.my-company.com/logo.png
- a
data-twic-src
referencingimage:web/banner.png
points tohttps://www.my-company.com/banner.png
Paths do not have to be on the same hierarchical level. For instance, the following configuration:
path | source images URL |
---|---|
/ | https://www.my-company.com/ |
/media | https://media.my-company.com/ |
would make it so:
https://<sub>.twic.pics/media/logo.png
still points tohttps://media.my-company.com/logo.png
- while
https://<sub>.twic.pics/banner.png
now points tohttps://www.my-company.com/banner.png
Keep in mind that doing so will make it impossible to access any image inside https://www.my-company.com/media/
.
Also:
- a path can point to a subfolder of your server rather than its root
- you can have more than two paths in your domain
- two paths can point to the same server
See this configuration as a more complex example:
path | source images URL |
---|---|
/ | https://www.my-company.com/assets/ |
/logo | https://media.my-company.com/images/logo/ |
/media | https://media.my-company.com/web/ |
Using Absolute URLs as Paths
Paths can have any format and as such, they can look like absolute URLs.
For instance, the following configuration:
path | source images URL |
---|---|
/https://www.my-company.com | https://www.my-company.com/ |
would make it so https://<sub>.twic.pics/https://www.my-company.com/assets/image.png
points to https://www.my-company.com/assets/image.png
.
Nothing impressive so far but it can come in handy when combined with the TwicPics Script.
Since the Script understands relative URLs in both data-twic-src
, data-twic-poster
and data-twic-background
attributes, you can seamlessly handle assets located on the same server as your webpages.
Let's say https://www.my-company.com/my-page.html
contains the following img
element:
<img data-twic-src="assets/image.png">
This will be rightfully understood as https://www.my-company.com/assets/image.png
and the image will be optimized by TwicPics automagically.
Multiple Subdomains
If you are a Pro or Enterprise customer, you can create Organizations and those Organizations can have multiple domains that can be named as you please.
This is pretty handy in order to switch from one environment to another, say between your production and staging environment.
Here is an example of such a two-domains configuration:
domain | path | source images URL |
---|---|---|
prod.twic.pics | / | https://www.my-company.com/assets/ |
/logo | https://media.my-company.com/images/logo/ | |
/media | https://media.my-company.com/web/ | |
staging.twic.pics | / | https://staging.my-company.com/assets/ |
/logo | https://media.my-company.com/images/logo/ | |
/media | https://media.my-company.com/web/ |
All you have to do now is reference the domain corresponding to the environment you are currently in (prod.twic.pics
or staging.twic.pics
) throughout your code base, which is usually as simple as setting a single variable and using it wherever you reference your TwicPics domain.
A Path of Many Options
There are a lot more options available on paths and you can learn more about them in the dedicated section of the documentation but, in a nutshell:
- authentication,
- fallbacks for non-existing assets,
- default manipulations,
- custom headers to be sent to your origin server,
- control over metadata filtering,
- canonical link header generation for SEO,
- and watermarking!
That's a lot so make sure to check them all out.