Custom Domain Proxy

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 make it easily identifiable when adding to a trusted domains list in a content blocker. For example, your email Preference CenterA page where users can manage their opt-in statuses for the Subscription Lists in your project. Preference Centers are presented within your app or website or as an Airship-hosted web page. URL could be preferences.[yourdomain].com instead of pages.airsp.co.

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:

• Android and iOS SDKs
• Web SDK
• Email preference centers
• Email unsubscribe links and double opt-in links

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 for your live/production projects.

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

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:

• Amazon CloudFront 
• Cloudflare 

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.

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

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

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 an Email Preference Center web page.

Test: Email unsubscribe and double opt-in links

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.

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

[[ua-unsubscribe]]

Test: Android and iOS SDKs

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+

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

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

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

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

import { UrbanAirship } from 'urbanairship-react-native';

Airship.takeOff({
    ...
    urlAllowList: [..., "https://analytics.example.com"],
    initialConfigUrl: "https://analytics.example.com"
});

  var config = AirshipConfig(
      ...
      initialConfigUrl: "https://analytics.exmaplpe.com",
      urlAllowList: [..., "https://analytics.example.com"]
  );

  Airship.takeOff(config);

Airship.takeOff({
    ...
    urlAllowList: [..., "https://analytics.example.com"],
    initialConfigUrl: "https://analytics.example.com"
});

Test: Web SDK

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:

<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>

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.

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.