# 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 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.](/docs/guides/messaging/features/preference-centers/) 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](https://www.airship.com/docs/developer/sdk-integration/android/) and [iOS](https://www.airship.com/docs/developer/sdk-integration/apple/) SDKs
- [Web SDK](https://www.airship.com/docs/developer/sdk-integration/web/)
- [Email preference centers](https://www.airship.com/docs/guides/messaging/features/preference-centers/)
- Email [unsubscribe links](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/) and [double opt-in links](https://www.airship.com/docs/guides/messaging/messages/content/email/email-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`.

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:

- [Amazon CloudFront](https://aws.amazon.com/cloudfront/)
- [Cloudflare](https://www.cloudflare.com/)

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](https://support.airship.com)  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](#cdn-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](#cdn-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](https://support.airship.com)  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 get your app key from your project dashboard: Next to your project name, select the dropdown menu (), then **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](https://www.airship.com/docs/guides/messaging/features/preference-centers/#directing-users-to-a-preference-center), 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](https://www.airship.com/docs/guides/messaging/features/preference-centers/#testing-an-email-preference-center-web-page).

### Test: Email unsubscribe and double opt-in links

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](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/) or [Double opt-in](https://www.airship.com/docs/guides/messaging/messages/content/email/email-double-opt-in-links/) 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](https://www.airship.com/docs/guides/messaging/messages/content/email/email-unsubscribe-links/), 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

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

Plain text example

```plaintext
[[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](https://support.airship.com) ; 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

Android Kotlin Android Java iOS Swift iOS Objective-C React Native Flutter Cordova

```kotlin
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`.

```java
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`.

```swift
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`.

```objc
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`.

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

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

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

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

  Airship.takeOff(config);
```

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

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

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

```html
<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)

```javascript
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](https://support.airship.com) . Reply to your original [proxy access request](#request-proxy-access-for-test-projects) 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 get your app key from your project dashboard: Next to your project name, select the dropdown menu (), then **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.