Superwall SDK integration

The Superwall integration enables server-to-server (S2S) forwarding of subscription lifecycle events from Superwall to Adjust. Superwall sends App Store subscription events to the Adjust S2S Events API.

The integration consists of two parts:

• Client-side: Pass device identifiers and the Adjust device ID (ADID) to the Superwall SDK so Superwall can include them in S2S requests.
• Server-side: Create event tokens in the Adjust dashboard and map them to Superwall subscription events in the Superwall dashboard.

Before you begin

Before you configure the Superwall integration, complete the following tasks:

1. Integrate the Adjust iOS SDK.
2. Integrate the Superwall iOS SDK.

Pass the Adjust ADID

The ADID is available after the device completes its first tracked session. Retrieve it in the Adjust session success callback and pass it to the Superwall SDK using setIntegrationAttributes.

1
extension AppDelegate: AdjustDelegate {
2
   func adjustSessionTrackingSucceeded(_ session: ADJSessionSuccess?) {
3
      guard let adid = session?.adid else { return }
4
      Superwall.shared.setIntegrationAttributes(
5
         [.adjustId: adid]
6
      )
7
   }
8
}

1
- (void)adjustSessionTrackingSucceeded:(ADJSessionSuccess *)session {
2
   NSString *adid = session.adid;
3
   if (adid == nil) { return; }
4
   [Superwall.sharedInstance
5
      setIntegrationAttributes:@{@"adjustId": adid}];
6
}

Pass additional attributes

Superwall forwards additional attributes on each S2S request. Adjust uses these identifiers for more robust device matching, and for campaign optimization. Collect the following attributes and pass them to Superwall using setUserAttributes:

The Superwall SDK automatically collects and forwards device_name and os_version on each S2S request.

Collect attributes

The Adjust SDK provides methods to retrieve IDFA, IDFV, and ATT status. You can use these instead of importing AdSupport and AppTrackingTransparency directly. You can also retrieve these values in the ATT authorization callback if you handle ATT through the Adjust SDK.

1
// IDFV — available without ATT authorization
2
Adjust.idfv { idfv in
3
   if let idfv {
4
      Superwall.shared.setUserAttributes(["idfv": idfv])
5
   }
6
}
7

8
// IDFA and ATT status — retrieve after ATT prompt response
9
Adjust.idfa { idfa in
10
   var attributes: [String: Any] = [
11
      "att_status": Adjust.appTrackingAuthorizationStatus()
12
   ]
13
   if let idfa, idfa != "00000000-0000-0000-0000-000000000000" {
14
      attributes["idfa"] = idfa
15
   }
16
   Superwall.shared.setUserAttributes(attributes)
17
}

1
// IDFV — available without ATT authorization
2
[Adjust idfvWithCompletionHandler:^(NSString *idfv) {
3
   if (idfv) {
4
      [Superwall.sharedInstance
5
         setUserAttributes:@{@"idfv": idfv}];
6
   }
7
}];
8

9
// IDFA and ATT status — retrieve after ATT prompt response
10
[Adjust idfaWithCompletionHandler:^(NSString *idfa) {
11
   NSMutableDictionary *attributes = [NSMutableDictionary dictionary];
12
   attributes[@"att_status"] =
13
      @([Adjust appTrackingAuthorizationStatus]);
14
   if (idfa && ![idfa isEqualToString:@"00000000-0000-0000-0000-000000000000"]) {
15
      attributes[@"idfa"] = idfa;
16
   }
17
   [Superwall.sharedInstance setUserAttributes:attributes];
18
}];

Configure the Superwall dashboard

Configure the following settings in the Superwall dashboard to enable event forwarding.

Event mapping

Create your event tokens in the Adjust dashboard, then add them to the Superwall dashboard to map each token to its corresponding Superwall subscription event. You need to create a separate event token for each event you want to forward. Events are only forwarded if a corresponding event token is configured.

For the complete list of supported events and their mapping logic, refer to the Superwall Adjust event mapping docs.

S2S security token

If you have S2S security enabled in Adjust, create an S2S security token and add it to the Superwall dashboard. Superwall includes the token as an Authorization: Bearer header on each S2S request.

Environment

Superwall automatically detects whether each event originates from a sandbox or production environment. Sandbox purchases made through TestFlight or with sandbox Apple IDs are forwarded with environment set to sandbox. Production purchases are forwarded with environment set to production. Adjust uses this field to separate test data from live data.

Revenue

For events that include revenue, Superwall forwards the purchase amount and currency to Adjust. You can configure the revenue reporting mode in the Superwall dashboard as either Revenue or Proceeds.

• Revenue: Gross revenue, which is the full purchase price.
• Proceeds: Net revenue after payment processor fees, such as App Store fees.

Events without revenue are sent without revenue parameters. Revenue is omitted when the calculated amount is below 0.001.

S2S request parameters

The following parameters are included on each event forwarded to the Adjust S2S Events API.