Hybrid Use Case Details

When sending out-of-app mobile events or website event data from your server to Singular, it’s essential to include the corresponding identifier from the Singular Mobile SDK or Web SDK. This ensures that the event activity is accurately attributed to the correct device.

Data Flow

There are two main methods to retrieve this device data:

1. Client-Managed Data Flow: This option is to capture all the required data points on the client and pass them to your server via your own API. This approach allows you to collect device identifiers, event data, and other necessary attributes directly from the client-side (e.g., mobile app or website) and forward them to your server, where you can process and send them to Singular using the Server-to-Server EVENT API.
2. Postback: This option is to configure the Singular Internal BI postback which allows Singular to send a postback to your designated endpoint with a JSON payload. This postback is delivered in real-time after an install, re-engagement, and/or in-app events occur. The payload will include all necessary data points required for successfully sending out-of-app server-side events. For detailed instructions on setting up the Internal BI postback, click [HERE].

Both options may require some server-side logic to maintain a device graph. If the Singular SDK detects a change in the device identifier, it is critical that your server is updated accordingly to ensure accurate tracking and attribution.

To implement the first option, where you capture device identifiers and parameters from the app and send them to your server for use with Singular API Endpoints, review the following articles for guidance:

• Review the Event Endpoint required parameters.
• Review the Server-to-Server Retrieving Device Data Guide for iOS and Android code samples to assist with the retrieval of specific device identifiers and device data points.

Review the general guidelines below to follow the general guidelines of a Server-to-Server configuration. With a Hybrid use-case you can omit the SESSION Endpoint as the Singular SDK will manage this for you.

Attribution for Apple Search Ads Campaigns (iOS)

Apple Search Ads is considered a Self-Attributing Network (SAN).  As of iOS 14.3, the Apple Search Ads integration is supported through two iOS frameworks:

• For iOS 14.2 and below, Apple Search Ads is supported via the iAd framework.
• For IOS 14.3 and above, Apple Search Ads is supported via the AdServices framework.
  

We recommend that both the iAd and AdServices frameworks are implemented until the iAd framework is deprecated at a future date.  Since AdServices is still a new Apple service, Singular will utilize both services but prioritize AdServices over iAd signals for attribution and reporting. 

For more information, see our Apple Search Ads integration documentation.

Implementing Apple Search Ads via iAd (iOS 14.2 and below)

1. Retrieving the Attribution Data:

To retrieve the attribution data, use the Apple Search Ads iAd API. Calling requestAttributionDetails(_:): returns a JSON object containing the attribution data.

For example:

#import <iAd/iAd.h>
  
    Class ADClientClass = NSClassFromString(@"ADClient");
  
    if (ADClientClass) {
        id sharedClient = [ADClientClass performSelector:@selector(sharedClient)];
        
        if ([sharedClient respondsToSelector:@selector(requestAttributionDetailsWithBlock:)]) {
            [sharedClient requestAttributionDetailsWithBlock:^(NSDictionary *attributionDetails, NSError *error) {
                if (attributionDetails && attributionDetails.count > 0) {
                    // REPORT attributionDetails FROM YOUR APP TO YOUR SERVER

                }
            }];
        }
    }

2. Sending the Attribution Data to Singular:

To share the attribution data with Singular, use the Event Notification endpoint to report an event with the reserved event name __iAd_Attribution__. Pass the JSON object you retrieved in the previous step as the value of the e parameter, as in the example below.

import requests
  import json
  
  SDK_KEY = '[sdk_key from Developer tools > SDK Integration > SDK keys]'
  EVENT_URL = 'https://s2s.singular.net/api/v1/evt'
  
  # !!! REPLACE WITH COLLECTED VALUE FROM APP !!!
  apple_attribution_data = {
    u'Version3.1': {
        u'iad-adgroup-id': u'1234567',
        u'iad-adgroup-name': u'Ad Group Name',
        u'iad-attribution': u'true',
        u'iad-campaign-id': u'1234567',
        u'iad-campaign-name': u'Search Campaign',
        u'iad-click-date': u'2016-05-21T12:19:31Z',
        u'iad-conversion-date': u'2016-05-21T12:19:41Z',
        u'iad-keyword': u'ballon',
        u'iad-lineitem-id': u'1234567',
        u'iad-lineitem-name': u'Line Item Name',
        u'iad-org-name': u'Cool Company',
        u'iad-purchase-date': u'2016-05-21T12:19:41Z'
    }
  }
  
  params = {
    'n': '__iAd_Attribution__',
    'e': json.dumps(apple_attribution_data),
    'a': SDK_KEY,
    'p': 'iOS',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'mo': 'iPhone9%2C4',
    'lc': 'en_US',
    'idfa': '8ECD7512-2864-440C-93F3-A3CABE62525B',
    'idfv': '38548D9F-3F73-4D4B-8545-9A920CC89191',
    'utime': 1483228800
  }
  
  result = requests.get(EVENT_URL, params=params)
  print result.json()

https://s2s.singular.net/api/v1/evt?n=__iAd_Attribution__&e=%7B%22Version3.1%22%3A%7B%22iad-purchase-date%22%3A%20%222016-10-25T22%3A24%3A35Z%22%2C%22iad-keyword%22%3A%20%22ballon%22%2C%22iad-adgroup-id%22%3A%20%221234567%22%2C%22iad-campaign-id%22%3A%20%221234567%22%2C%22iad-lineitem-id%22%3A%20%221234567%22%2C%22iad-org-id%22%3A%20%224070%22%2C%22iad-org-name%22%3A%20%22Cool%20Company%22%2C%22iad-campaign-name%22%3A%20%22Search%20Campaign%22%2C%22iad-conversion-date%22%3A%20%222016-05-21T12%3A19%3A41Z%22%2C%22iad-conversion-type%22%3A%20%22Redownload%22%2C%22iad-click-date%22%3A%20%222016-05-21T12%3A19%3A31Z%22%2C%22iad-attribution%22%3A%20%22true%22%2C%22iad-adgroup-name%22%3A%20%22Ad%20Group%20Name%22%2C%22iad-lineitem-name%22%3A%20%22Line%20Item%20Name%22%7D%7D&a=SDK_KEY&p=iOS&i=com.singular.app&ip=10.1.2.3&ve=9.2&ma=Apple&mo=iPhone8%2C1&lc=en_US&idfa=8ECD7512-2864-440C-93F3-A3CABE62525B&idfv=38548D9F-3F73-4D4B-8545-9A920CC89191&utime=1568948680

Implementing Apple Search Ads via AdServices (iOS 14.3 and above)

1. Retrieving the attribution token:

Retrieve the attribution token using attributionToken() as soon the app initializes for the first time after an install or re-install. 

For example:

#import <AdServices/AdServices.h> 

NSError *error = nil;
Class AAAttributionClass = NSClassFromString(@"AAAttribution");
if (AAAttributionClass) {
    NSString *attributionToken = [AAAttributionClass attributionTokenWithError:&error];
    if (!error && attributionToken) {
        // Handle attributionToken

    }
}

Notes:

2. Send the attribution token to Singular:

URL encode the token and send the token to Singular via the session notification endpoint, appended to the &attribution_token= parameter.   This token should be sent on the first session after every install and re-install to enable Singular to track Apple Search Ads downloads and re-downloads.   

Important: Sending the Google Play Install Referrer (Android)

The install referrer contains information about who sent a user to the Google Play Store. When the install referrer is available to Singular, it provides the most accurate way to attribute installs. Retrieve this value and pass it along to Singular on the first session notification call. It is required for some important Singular features, such as receiving Facebook data in our User-Level Exports, sharing it with Data Destinations, and sending postbacks.

Google Play collects referrer information when a user arrives at the store. If the user later installs the app they were directed to, Google Play makes the information available to the app. For more information, see Google's developer documentation.

To share the install referrer with Singular:

1. When the app is opened for the first time, retrieve the install referrer using the Play Install Referrer API.

2. Report a session to Singular using the Session Notification endpoint including the parameter install_ref. This parameter is JSON-encoded and has the following attributes:

   Attribute	Description
   referrer	The referrer value as retrieved from the Play Install Referrer API. This is a JSON object, so make sure to encode it as a string.
   referrer_source	Specify "service".
   clickTimestampSeconds	The click timestamp as received from the Play Install Referrer API (e.g., "1550420123").
   installBeginTimestampSeconds	The time that the install started, as received from the Play Install Referrer API.
   current_device_time	The time in the current device, in milliseconds (e.g., "1550420454906").

The following is sample code for reporting the install referrer event:

import requests
  import json
  
  SDK_KEY = '[sdk_key from Developer tools > SDK Integration > SDK keys]'
  LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
  referrer_values = {
        "referrer": "tracking_id%3D123456789&utm_source%3Dmdotm%26utm_medium%3Dbanner%26utm_campaign%3Dcampaign",
        "referrer_source" : "service",
        "clickTimestampSeconds" : 1550420123,
        "installBeginTimestampSeconds" : 1550420123,
        "current_device_time" : 1550420454906
      }

referrer_values = json.dumps(referrer_values, separators=(',',':'))
  
   params = {
       'a': SDK_KEY,
       'p': 'Android',
       'i': 'com.singular.app',
       'ip': '10.1.2.3',
       've': '9.2',
       'ma': 'samsung',
       'mo': 'SM-G935F',
       'lc': 'en_US',
       'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
       'andi': 'fc8d449516de0dfb',
       'utime': 1483228800,
       'dnt': 0,
       'install':'true',
       'n': 'MyCoolApp',
       'c': 'wifi',
       'cn': 'Comcast',
       'bd': 'Build/13D15',
       'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1',
       'app_v':'1.2.3',
       'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1',
       'ddl_enabled':'false',
       'install_source': 'com.android.vending',
       'install_time': 1510040127,
       'update_time': 1510090877,
      'custom_user_id': '123456789abcd',
      'install_ref' : referrer_values
   }
  
   result = requests.get(LAUNCH_URL, params=params)
   print result.json()

https://s2s.singular.net/api/v1/launch?aifa=8ecd7512-2864-440c-93f3-a3cabe62525b&andi=fc8d449516de0dfb&p=Android&a=SDK_KEY&i=com.singular.app&ip=10.1.2.3&ve=9.2&dnt=0&n=MyCoolApp&dnt=0&c=wifi&cn=Comcast&lc=en_US&bd=Build%2FMMB29K&ma=samsung&mo=SM-G935F&custom_user_id=123456789abcd&install_ref=%7B%22installBeginTimestampSeconds%22%3A%221568939453%22%2C%22referrer%22%3A%22utm_source%3Dgoogle-play%26utm_medium%3Dorganic%22%2C%22clickTimestampSeconds%22%3A%220%22%2C%22referrer_source%22%3A%22service%22%2C%22current_device_time%22%3A%221568944524%22%7D%0A

Meta Install Referrer Attribution (Android)

"Meta Referrer" is an Android-specific measurement solution introduced by Facebook to allow advertisers access to granular user-level attribution data for Android app installs (see Facebook's data policies). It is comprised of implementing both "Google Play Install Referrer" (see "Passing Google Install Referrer") and "Meta Install Referrer" technologies for app install measurement. Read more about Meta Referrer in the FAQ on the topic.

To share Meta Install Referrer information with Singnular:

1. When the app is opened for the first time, retrieve the Meta install referrer according to Meta's documentation.

2. Report a session to Singular using the Session Notification endpoint including the parameter meta_ref. This parameter is JSON-encoded and has the following attributes:

   Attribute	Description
   is_ct	The "is_ct" as received from the Meta Install Referrer. (e.g. 0 or 1)
   install_referrer	The "install_referrer" as received from the Meta Install Referrer
   actual_timestamp	The "actual_timestamp" as received from the Meta Install Referrer (e.g., 1693978124).

Enabling Deep Linking

Deep Linking Prerequisites

The client App must be configured to recognize the Singular Link as an iOS Universal Link or an Android App Link. Follow the Singular Links Prerequisites guide to enable iOS and Android deeplinking.

Implementing Deep Links

When the app is opened through a deep link, capture and add the openURL to the Session Notification request sent to Singular by append the URL value to the openuri parameter. This is required when using Singular Links.

The client App code must be updated to parse and handle the Deeplink Parameters from the Singular Links URL. In the event of a successful deep link caused by a Singular Link, the following parameters may be present on the openURL:

_dl, _ios_dl, _android_dl, _p

• _ios_dl and _android_dl will be present on a link when the link was generated to deep link on both iOS AND Android with different deeplink values for each platform.
• If deep link values are the same for iOS AND Android, only _dl will be present.
• If additional data is passed in the passthrough parameter the _p will be present.

Deep Link Handler Code Sample

The App must have handler code capable of parsing the openURL and handling it appropriately. Find the example below to demonstrate how you might parse the Singular Link parameters.

class DeepLinkHandler {
  func handleURL(_ url: URL) {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
      return
    }

    var params: [String: String] = [:]

    // Parse query parameters

    if let queryItems = components.queryItems {
      for item in queryItems {
        switch item.name {
        case "_dl":
          params["deeplink"] = item.value
        case "_ios_dl":
          params["ios_deeplink"] = item.value
        case "_p":
          params["passthrough"] = item.value
        default:
          break
        }
      }
    }

    // Handle the parsed parameters

    processDeepLinkParameters(params)
  }

  private func processDeepLinkParameters(_ params: [String: String]) {
    // Process the parameters as needed

    print("Processed parameters: \(params)")
  }
}

// In SceneDelegate or AppDelegate

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
  guard let url = URLContexts.first?.url else { return }
  let handler = DeepLinkHandler()
  handler.handleURL(url)
}

class DeepLinkHandler {
    fun handleDeepLink(intent: Intent) {
        val data: Uri? = intent.data

        data?.let { uri ->
            val params = mutableMapOf<String, String>()

            // Parse query parameters

            uri.queryParameterNames?.forEach { name ->
                when (name) {
                    "_dl" -> params["deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_android_dl" -> params["android_deeplink"] = uri.getQueryParameter(name) ?: ""
                    "_p" -> params["passthrough"] = uri.getQueryParameter(name) ?: ""
                }
            }

            processDeepLinkParameters(params)
        }
    }

    private fun processDeepLinkParameters(params: Map<String, String>) {
        // Process the parameters as needed

        println("Processed parameters: $params")
    }
}

// In your Activity

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Handle deep link if activity was launched from a deep link

        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        // Handle deep link if app was already running

        intent?.let { DeepLinkHandler().handleDeepLink(it) }
    }
}

Deferred Deep Link Support

When the app is opened for the first time since the install, enable the deferred deep linking flow by adding the following parameters when you report the Session to Singular:

• install=true
• ddl_enabled=true

Singular looks to see if the app was installed through a tracking link that included a deferred deep link. If it was, the Session request returns the following values in the response to your server:

• deferred_deeplink - the deep link address. This is what you need to parse to show the users the right product or experience.
• deferred_passthrough - any passthrough parameters added to the deep link.

The client App should include code to handle the Deferred Deeplink, and Passthrough Parameters provided in the response from the Singular SESSION API and handle the data appropriately. The response JSON from the SESSION notification with a deferred deeplink value will look like:

{
 "deferred_deeplink":"myapp://deferred-deeplink",
 "status":"ok",
 "deferred_passthrough":"passthroughvalue"
}

Using Dynamic Passthrough Parameters

Singular tracking links can include dynamic passthrough parameters (learn more). If your organization has set up dynamic passthrough parameters for a link, the deep link URL includes the _p parameter followed by a URL-encoded JSON string value or an unstructured string which you can use to show the user the appropriate content or experience.

Resolving Short Links

When the App is opened from a shortened Singular Link, the following parameter should be included on the launch request to notify the Singular Session endpoint that the openURL sent in openuri parameter should be resolved to the Singular long link.

• singular_link_resolve_required=true

Singular will return the unshortened long link and the App Developer can parse the deep link and passthrough parameters in the link handler, as previously noted.

Sample Response

{
   "status":"ok",
   "resolved_singular_link":"https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

Sample Custom Revenue Event

import requests

params = {
    "a": "sdk_key_here",
    "p": "Android",
    "i": "com.singular.app",
    "ip": "10.1.2.3",
    "ve": "9.2",
    "aifa": "8ecd7512-2864-440c-93f3-a3cabe62525b",
    "asid": "edee92a2-7b2f-45f4-a509-840f170fc6d9",
    "n": "RevenueEventName",
    "amt": "2.50",
    "cur": "USD",
    "is_revenue_event": "true",
    "purchase_receipt": {
        'orderId"': "GPA.1234",
        "packageName": "com.example",
        "productId": "com.example.product",
        "purchaseTime": 1417113074914,
        "purchaseState": 0,
        "purchaseToken": "hakfcimbkargpM",
    },
    "receipt_signature": "TyVJfHg8OAoW7W4wuJtasr5agEDMnNXvhfrw==",
    "purchase_product_id": "com.example.product",
    "purchase_transaction_id": "GPA.1234-1234-1234-12345",
}

response = requests.get("https://s2s.singular.net/api/v1/evt", params=params)
print(response.json())

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=RevenueEventName
    &amt=2.50
    &cur=USD
    &is_revenue_event=true
    &purchase_receipt={"orderId":"GPA.1234","packageName":"com.example","productId":"com.example.product","purchaseTime":1417113074914,"purchaseState":0,"purchaseToken":"hakfcimbkargpM"}
    &receipt_signature=TyVJfHg8OAoW7W4wuJtasr5agEDMnNXvhfrw==
    &purchase_product_id=com.example.product
    &purchase_transaction_id=GPA.1234-1234-1234-12345 HTTP/1.1
Host: s2s.singular.net
Accept: application/json

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=sdk_key_here" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.singular.app" \
  --data-urlencode "ip=10.1.2.3" \
  --data-urlencode "ve=9.2" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=RevenueEventName" \
  --data-urlencode "amt=2.50" \
  --data-urlencode "cur=USD" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "purchase_receipt={\"orderId\":\"GPA.1234\",\"packageName\":\"com.example\",\"productId\":\"com.example.product\",\"purchaseTime\":1417113074914,\"purchaseState\":0,\"purchaseToken\":\"hakfcimbkargpM\"}" \
  --data-urlencode "receipt_signature=TyVJfHg8OAoW7W4wuJtasr5agEDMnNXvhfrw==" \
  --data-urlencode "purchase_product_id=com.example.product" \
  --data-urlencode "purchase_transaction_id=GPA.1234-1234-1234-12345"

To retrieve this value, add the following code to your app:

// ReceiptManager.h

@interface ReceiptManager : NSObject
+ (nullable NSString *)getInstallReceipt;
@end

// ReceiptManager.m

#import <StoreKit/StoreKit.h>

@implementation ReceiptManager

+ (nullable NSString *)getInstallReceipt {
    if (@available(iOS 18.0, *)) {
        dispatch_semaphore_t semaphore = dispatch_semaphore_create(0);
        __block NSString *result = nil;
        
        [SKPaymentQueue.defaultQueue addTransactionObserver:[[SKPaymentTransactionObserver alloc] init]];
        
        if (@available(iOS 18.0, *)) {
            [AppTransaction.shared fetchWithCompletionHandler:^(AppTransaction *transaction, NSError *error) {
                if (error) {
                    NSLog(@"Failed to get app transaction: %@", error.localizedDescription);
                } else {
                    result = transaction.jwsRepresentation;
                }
                dispatch_semaphore_signal(semaphore);
            }];
        }
        
        dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER);
        return result;
        
    } else {
        NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
        if (!receiptURL) {
            NSLog(@"Receipt URL not found");
            return nil;
        }
        
        NSError *error = nil;
        NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL 
                                                   options:NSDataReadingUncached 
                                                     error:&error];
        
        if (error) {
            NSLog(@"Failed to read receipt: %@", error.localizedDescription);
            return nil;
        }
        
        return [receiptData base64EncodedStringWithOptions:0];
    }
}

@end

import Foundation
import StoreKit

class ReceiptManager {
    static func getInstallReceipt() -> String? {
        if #available(iOS 18.0, *) {
            // Synchronous wrapper for async code

            let semaphore = DispatchSemaphore(value: 0)
            var result: String?
            
            Task {
                do {
                    let transaction = try await AppTransaction.shared
                    result = transaction.jwsRepresentation
                    semaphore.signal()
                } catch {
                    debugPrint("Failed to get app transaction: \(error.localizedDescription)")
                    semaphore.signal()
                }
            }
            
            semaphore.wait()
            return result
            
        } else {
            // Legacy receipt fetching

            guard let receiptURL = Bundle.main.appStoreReceiptURL else {
                debugPrint("Receipt URL not found")
                return nil
            }
            
            do {
                let receiptData = try Data(contentsOf: receiptURL, options: .uncached)
                return receiptData.base64EncodedString(options: [])
            } catch {
                debugPrint("Failed to read receipt: \(error.localizedDescription)")
                return nil
            }
        }
    }
}