Custom Domain Proxy

Send Airship traffic through your own domain.

Airship traffic is routed using domains including urbanairship.com, aswpapius.com, and airsp.co. Customers viewing these domains in URLs will likely not associate them with your brand. The domains may also be denied by content blockers, resulting in disabled Airship features.

Substituting your own domain instead can provide a consistent brand experience for your users and it is easily identifiable when adding to a trusted domains list in a content blocker. This is accomplished by setting up a custom domain proxy, which relays requests (traffic) from your custom domain to Airship instead of directly to Airship.

Supported features

Custom domains are supported for the following Airship features:

Configuration process

Complete these steps to configure a custom domain:

  1. Configure your CDN proxy. This includes:
    • Creating your custom domain. We recommend creating a dedicated subdomain, e.g., analytics.example.com.
    • Pointing traffic from your custom domain to Airship. You will specify a CDN origin based on the location of your Airship data center.
  2. Request proxy access. Airship will configure feature support your test projects.
  3. Test the configured features in your test projects.
  4. After a successful test, request production support. Airship will configure feature support your live/production projects.

In this document, configuration steps use an example subdomain: analytics.example.com.

 Note

You may use a configured CDN to support more than one Airship project. We recommend trying the custom domain on a test project first, and then moving to your live/production project once it has passed testing.

Requirements

In order to configure a custom domain, you will need access to the following:

  • Your domain’s DNS configuration
  • A CDN proxy, and access to configure it
  • A security certificate issued for the proxy domain

You must provide your own CDN, which you will configure with your own TLS certificates, and point to an origin we provide. We have tested the following providers:

 Note

For assistance with a CDN product, please contact that product’s support team. Airship Support is unable to help you directly for those products.

CDN origin

The origin you use as a target for your CDN depends on your project’s data center:

  • North American data center: ext.airship.com
  • EU data center: ext.airship.eu

Contact Airship Support if you are unsure which value to use.

Configuration steps

CDN proxy configuration varies depending on your CDN provider. We provide information for configuring Cloudflare and Amazon CloudFront.

 Important

We recommend using a dedicated subdomain for the CDN, as you will be passing all traffic from the domain to Airship. We do not support any setup which routes traffic for only some paths.

Configure your CDN proxy: Amazon CloudFront

Create a new CloudFront distribution with the following settings:

  • Origin: The correct origin for your data center: ext.airship.com or ext.airship.eu.
  • Viewer protocol policy: HTTPS only
  • Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
  • Cache key and origin requests
    • Cache policy: CachingOptimized
    • Origin request policy: AllViewer

The remaining settings are your responsibility, but you must provide a valid certificate.

Configure your CDN proxy: Cloudflare

 Note

Cloudflare is typically configured for an entire domain (e.g., example.com), not just a subdomain. This is the only configuration Airship has tested, and these instructions assume you have already successfully configured Cloudflare for your domain.

Under Cloudflare’s DNS management, add a new subdomain record:

  • Type: CNAME
  • Name: Your chosen subdomain name, e.g., analytics
  • Content/Origin: The correct origin for your data center: ext.airship.com or ext.airship.eu
  • Proxy Status: Proxied
 Important

In order for Cloudflare to work with an Airship origin, the SSL/TLS mode must be set to Full (strict).

Request proxy access for test projects

Once your proxy is configured, you can visit the custom domain in a web browser, however you will receive a generic “Error 404” message. This is expected.

Next, contact Airship Support with a request for your custom domain to be configured for proxy access. Provide this information:

  • The Airship project app keys for test projects you wish to configure to use the custom domain. You can view your app key in Settings » Project Details.
  • Your custom domain, e.g. analytics.example.com
  • The features you wish to enable: Email preference centers and/or the Web SDK.

Airship Support will confirm when they complete configuration. You can then test the proxy in a test (non-live/production) project.

Test: Email preference center

For an email preference center, edit an existing preference center URL, replacing the default Airship domain pages.airsp.co with your custom domain:

  • Default: https://pages.airsp.co/pages/<app_key>/<page_id>?channel_id=<channel_id>
  • Custom: https://analytics.example.com/pages/<app_key>/<page_id>?channel_id=<channel_id>

The preference center should work with no further changes. See also: Testing the appearance of an email preference center.

 Important

The custom domain proxy feature will not affect email link tracking domains. You may not use the same domain for email tracking links and a custom domain proxy.

When sending an email, you may use Unsubscribe / List unsubscribe or Double opt-in links to allow end users to update their opt in status. When using these links, Airship provides a default “success” landing page if you do not specify your own.

When using the custom domain proxy feature for these links, they will use your custom domain instead of the Airship default domains.

To test this feature, send an email to yourself that includes an Unsubscribe link, without specifying a redirect URL. After following the link in the email you receive, you should be redirected through your custom domain and arrive at a default landing page on that same domain.

HTML example
<a data-ua-unsubscribe="1">Unsubscribe</a>

Plain text example
[[ua-unsubscribe]]

Test: Android and iOS SDKs

 Important

You should test the domain configuration on a test project to avoid interruptions to your audience. An invalid configuration will prevent the SDK from communicating with Airship, and this configuration can only be enabled for your full audience.

Enabling a custom domain for Android and iOS SDK traffic can only be done by contacting Airship Support; you will coordinate with our support staff to determine when the setting should be enabled for your Test and Live projects.

Once a custom domain is enabled for your project, the configuration will automatically be pulled by the SDK once its local cache expires. This will allow you to test SDK communications, however the initial configuration will still be pulled from Airship domains. To fetch this initial configuration from your custom domain you must update your application’s configuration with the new “initial configuration URL” setting, which requires the following SDK versions:

  • Android: 16.8.0+
  • iOS: 16.10.0+

Configuring a custom domain

val config = AirshipConfigOptions.Builder()
    ...
    .setInitialConfigUrl("https://analytics.example.com")
    .setUrlAllowList(arrayOf(..., "https://analytics.example.com"))
    .build()

Apps that load config from a properties file can set the domain using the keys urlAllowList and initialConfigUrl.

AirshipConfigOptions config = AirshipConfigOptions.newBuilder()
        ...
        .setInitialConfigUrl("https://analytics.example.com")
        .setUrlAllowList(new String[]{..., "https://analytics.example.com"})
        .build();

Apps that load config from a properties file can set the domain using the keys urlAllowList and initialConfigUrl.

let config = Config()
...
config.initialConfigURL = "https://analytics.example.com"
config.urlAllowList = [..., "https://analytics.example.com"]

Apps that load config from a plist can set the domain using the keys urlAllowList and initialConfigURL.

UAConfig *config = [[UAConfig alloc] init];
...
config.initialConfigURL = @"https://analytics.example.com";
config.urlAllowList = @[..., @"https://analytics.example.com"];

Apps that load config from a plist can set the domain using the keys urlAllowList and initialConfigURL.

Test: Web SDK

 Important

You should test the domain configuration on a staging deployment of your website to avoid interruptions.

The Web SDK’s initialization code must be updated to specify the new SDK source URL, as well as the API endpoints. These will have the same value. For example:

snippet.html (SAMPLE ONLY)
<script type="text/javascript">
!function(n,t,c,e,u){function r(n){try{f=n(u)}catch(n){return h=n,void i(p,n)}i(s,f)}function i(n,t){for(var c=0;c<n.length;c++)d(n[c],t);
}function o(n,t){return n&&(f?d(n,f):s.push(n)),t&&(h?d(t,h):p.push(t)),l}function a(n){return o(!1,n)}function d(t,c){
n.setTimeout(function(){t(c)},0)}var f,h,s=[],p=[],l={then:o,catch:a,_setup:r};n[e]=l;var v=t.createElement("script");
v.src=c,v.async=!0,v.id="_uasdk",v.rel=e,t.head.appendChild(v)}(window,document,'https://analytics.example.com/notify/v1/ua-sdk.min.js',
  'UA',
  {
    appKey: '<app_key>',
    token: '<bearer_token>',
    vapidPublicKey: '<vapid_public_key>',

    // this configuration key is new, and needed for the custom domain
    apiUrl: 'https://analytics.example.com'
  })
</script>
push-worker.js (SAMPLE ONLY)
importScripts('https://analytics.example.com/notify/v1/ua-sdk.min.js')
uaSetup.worker(self, {
  defaultIcon: '<icon_url>',
  defaultTitle: 'Example Site',
  defaultActionURL: 'https://example.com',
  appKey: '<app_key>',
  token: '<bearer_token>',
  vapidPublicKey: '<vapid_public_key>',

  // this configuration key is new, and needed for the custom domain
  apiUrl: 'https://analytics.example.com'
})

Make the following changes:

  • Update the path to ua-sdk.min.js to the custom domain, keeping the path the same as before.
  • Add a new configuration key apiUrl, containing the custom domain and protocol, without a trailing slash.
 Note

You must update the initialization code both in the snippet in your web pages and in your push worker, e.g., push-worker.js.

Once configured, you should see any SDK traffic being sent from the browser through your custom domain without error.

Request support for live/production projects

After your configuration has been tested with a successful outcome, once again contact Airship Support. Reply to your original proxy access request with a request to have the configuration committed to your live/production projects and provide:

  • The Airship project app keys for live projects you wish to configure to use the custom domain. You can view your app key in Settings » Project Details.

This final step by Support ensures that any URLs generated by the Airship dashboard will reflect the correct settings for your custom domain.