Application Proxies: Front End Development

An application proxy is a feature that fetches and displays data on a Shopify shop page from an outside location that you, the developer, specify. For app developers, this means that the content on these proxy pages can be dynamic; capable of being updated as much as you feel necessary. App developers can use application proxies to display image galleries, statistics and custom forms, just to name a few examples.

Application proxies do not have to be set up before installation to start working. Application proxies added to an app after it is installed will update its existing install-base.

As a bonus, through the application proxy, it is possible to have Shopify render Liquid responses from the Proxy URL. Liquid is Shopify's customization engine and rendering a Liquid response displays your proxy page as if it were a part of the shops theme.

This resource covers:


Add a proxy to your app

Login to your Shopify Partners dashboard. Navigate to the "Apps tab."

Click on your Apps name. Click the Edit app settings button and find the "App Proxy" section near the bottom.

Screenshot of the Application Proxy section.

Click on the Add application proxy button.

Set the Proxy URL to the URL within your app's domain where you would like these requests to be proxied.

It should be noted that Shopify will not recognize localhost or example.com as the proxy URL and will return an error.

Then set a default sub-path for where the application should respond when it is installed in a shop.

Screenshot of how to set the Proxy URL.

Finish by pressing the Add application proxy button.

What the store owner sees

After a store owner installs an app with a proxy, they have the ability to change the sub-path. The sub-path is where the application proxy will be accessed from a store owners own shop (Apps > Manage Apps). Store owners may choose to change the sub-path so that the URL in the location bar makes the proxy page appear like it is being hosted in their store instead of externally. Ultimately, the sub-path is purely for shop aesthetics and will not affect the actual location of the proxy URL (edited sub-paths will still be forwarded to the proxy URL).

Here's what that looks like:

store owners view of the Application Proxy.

Issue a proxy request

When Shopify receives an HTTP request for a proxied path, it will forward that request to the specified Proxy URL. For example, when the following HTTP request is sent from the client user agent:

GET /apps/awesome_reviews/extra/path/components?extra=1&extra=2 HTTP/1.1
  Host: shop-domain.com
  Cookie: csrftoken=01234456789abcdef0123456789abcde;
  _session_id=1234456789abcdef0123456789abcdef;
  _secure_session_id=234456789abcdef0123456789abcdef0

Shopify will forward the request using the specified Proxy URL.

Given that the Proxy URL is set to https://proxy-domain.com/proxy, the client's IP address is 123.123.123.123 and the applications shared secret is hush, the forwarded request will look like the following:

GET/proxy/extra/path/components?extra=1&extra=2&shop=shop-name.myshopify.com&path_prefix=%2Fapps%2Fawesome_reviews&timestamp=1317327555&signature=a9718877bea71c2484f91608a7eaea1532bdf71f5c56825065fa4ccabe549ef3 HTTP/1.1
  Host: proxy-domain.com
  X-Forwarded-For: 123.123.123.123

Cookies are not supported for the application proxy, since the application is accessed through the shop's domain. Shopify will strip the Cookie header from the request and Set-Cookie from the response.

The forwarded request adds the following parameters:

  • shop: The myshopify.com domain for the shop.
  • path_prefix: The proxy sub-path prefix at which the shop was accessed. In this case, it's/apps/awesome_reviews, which was replaced in the forwarded request URL with the proxy application's Proxy URL.
  • timestamp: The time in seconds since midnight of January 1, 1970 UTC.
  • signature: Verifies that the request was sent by Shopify. A hexadecimal encoded SHA-256 HMAC of the other parameters, split on the "&" character, unencoded, sorted, concatenated and using the applications Shared Secret as the HMAC key.

Security: Calculate a digital signature

Just like our webhooks, we sign all our proxy requests.

In Ruby, the algorithm for calculating the signature looks like this using the ruby-hmac gem:

require 'rubygems'
require 'openssl'
require 'rack/utils'
SHARED_SECRET = 'hush'

# Use request.query_string in rails
query_string = "extra=1&extra=2&shop=shop-name.myshopify.com&path_prefix=%2Fapps%2Fawesome_reviews&timestamp=1317327555&signature=a9718877bea71c2484f91608a7eaea1532bdf71f5c56825065fa4ccabe549ef3"

query_hash = Rack::Utils.parse_query(query_string)
# => {
#   "extra" => ["1", "2"],
#   "shop" => "shop-name.myshopify.com",
#   "path_prefix" => "/apps/awesome_reviews",
#   "timestamp" => "1317327555",
#   "signature" => "a9718877bea71c2484f91608a7eaea1532bdf71f5c56825065fa4ccabe549ef3",
# }

# Remove and save the "signature" entry
signature = query_hash.delete("signature")

sorted_params = query_hash.collect{ |k, v| "#{k}=#{Array(v).join(',')}" }.sort.join
# => "extra=1,2path_prefix=/apps/awesome_reviewsshop=shop-name.myshopify.comtimestamp=1317328872"

calculated_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::Digest.new('sha256'), SHARED_SECRET, sorted_params)
raise 'Invalid signature' if signature != calculated_signature

The request method and request body will be forwarded, so content from form submission and AJAX requests can be used in the proxy application. In this case, the URL will still contain the query parameters added by the proxy (i.e. shop, path_prefix, timestamp, and signature) even when the body also contains URL encoded parameters.


Proxy response

If the HTTP response from the Proxy URL has Content-Type: application/liquid set in its headers, Shopify will evaluate and render any Liquid code in the request's body in the context of the shop using the shop's theme. When used the right way, it can automatically make your app look like it belongs as part of the shop without any manual intervention.

Otherwise, the response will be returned directly to the client. 30* redirects will be followed in case you need that sort of thing.

Ready to put what you've learned into action?

Build an online store with Shopify Try it Free

Experience the future of retail now

Shopify Point of Sale Try it Free