SDK Integration Prerequisites

Essential preliminary steps required before any Singular SDK integration, covering planning, app registration, domain configuration, and testing preparation.

Required Preliminary Steps: The following steps are required for any Singular SDK integration.

Learn how to plan SDK integration, register apps for development, create domains for tracking links, and prepare testing workflows during and after implementation.

Target Audience	Business Teams, Marketing Teams, Development Teams
Prerequisites	Singular account access, App Bundle ID, Marketing KPI definitions

Integration Overview

Cross-Functional Collaboration

Successful Singular SDK integration requires collaboration between marketing, business, and development teams to define requirements, configure tracking, and validate implementation.

Team Responsibilities:

Team	Responsibilities
Marketing/Business	Define event tracking requirements and marketing KPIs Select link domain for campaign tracking Configure production app settings in Singular platform Review and approve testing procedures
Development	Implement SDK integration following technical specifications Register development/testing app in Singular platform Configure deep linking and tracking link handlers Execute testing procedures and validation

Step 1: Plan SDK Integration

Before starting SDK integration, marketing and business teams must answer key questions enabling development team to implement appropriate SDK features and functionality.

Children's Privacy Compliance

Apps Directed at Children

Question: Is this app explicitly directed at children?

Apps targeting children must comply with Play Store and App Store policies safeguarding children's privacy. Singular offers specialized SDKs for compliance.

Recommended Solution: Use Singular's Kids Apps SDKs, which help comply with privacy policies by not capturing device identifiers.

Deep Linking Configuration

Deep Link Handling

Question: Will the app handle deep links?

Deep linking enables directing users to specific content within app from external sources like marketing campaigns, push notifications, or web pages.

Implementation Requirements:

Prerequisites: Follow Singular Links Prerequisites for domain and platform configuration
Deep Link Handler: Implement handler in code as explained in relevant SDK guide (iOS, Android, React Native, etc.)
Testing: Validate deep link functionality using Testing Console and manual testing procedures

Event Tracking Strategy

In-App Event Planning

Question: Will the app track user events?

Singular collects in-app event data to analyze campaign performance and measure KPIs. Event strategy should align with marketing objectives and user value measurement.

Standard Events

Standard Event Benefits

Singular supports variety of standard events commonly used across verticals and often supported by ad networks for reporting and optimization.

Advantages:

Automatic Recognition: Singular recognizes standard events automatically and adds to Events list without manual definition
Partner Support: Ad networks support standard events for campaign optimization and reporting
Industry Alignment: Consistent naming across platforms and partners
Best Practice: Recommended approach whenever events match standard definitions

Standard Event Attributes

For each standard event, pass recommended standard attributes for complete data capture and partner compatibility.

Example: sng_content_view event (user views product) should include:

sng_attr_content_type - Type of content viewed
sng_attr_content_id - Unique content identifier
sng_attr_content - Content description or name

Event Strategy Resources

UA/marketing/business teams should compile event list based on Marketing KPIs using following resources:

How to Track In-App Events - Event planning and implementation guide
Singular Standard Events: Full List and Recommended Events by Vertical - Complete standard event reference

Platform-Specific Event Names

Developer Note: SDK integration may require slightly different event/attribute name formats (all caps, no underscores, etc.) based on development platform.

Platform-Specific Lists:

Custom Events

Custom Event Definition

If events don't match Singular's standard events, define custom events with custom names for specific tracking requirements.

Custom Event Guidelines:

Character Limit: Maximum 32 characters
Language: Recommend English names for compatibility with ad network partners receiving events from Singular
Naming Convention: Use descriptive, consistent naming for clarity and maintenance
Documentation: Maintain event catalog documenting custom event names and purposes

Event Tracking Scope

Best Practice: Send events to Singular only if needed for marketing-related purposes. If event not significant as campaign performance KPI or user value indicator, that event should not be tracked by Singular.

Event Selection Criteria:

Marketing Relevance: Event provides insights for campaign optimization
KPI Measurement: Event contributes to key performance indicators
User Value: Event indicates user engagement or monetization
Partner Optimization: Event used by ad networks for campaign targeting

iOS-Specific Configuration

SKAdNetwork Implementation

Question (iOS): Will the app implement SKAdNetwork?

SKAdNetwork enables privacy-preserving attribution on iOS without requiring user-level tracking permission. Singular supports two implementation modes.

SKAdNetwork Modes:

Managed Mode: Singular automatically updates conversion values based on predefined rules
Manual Mode: Your app updates conversion values directly using SDK methods

App Tracking Transparency

Question (iOS): Will the app request user permission to share tracking information (ATT)?

Singular recommends displaying ATT prompt because user opt-in enables sharing device ID (IDFA), improving install attribution accuracy.

Configuration Requirement: If displaying ATT prompt, configure SDK to delay Singular initialization until user responds to prompt. This ensures attribution captures correct tracking authorization status.

ATT Implementation:

Prompt Timing: Display ATT prompt before initializing Singular SDK
SDK Configuration: Use SDK configuration options to wait for ATT response
IDFA Capture: If user grants permission, IDFA collected for deterministic attribution
Fallback Attribution: If user denies permission, attribution uses fingerprinting and IDFV

Step 2: Register Development App

Register development/testing app in Singular platform using separate Bundle ID from production app to maintain data separation during testing.

Bundle ID Strategy

Development vs Production

Same SDK Key and Secret Key used for both production and testing apps. Once data saved in Singular, it cannot be deleted.

Recommended Approach: Use different Bundle Identifier for test app to keep data separate from production app. Change Bundle ID to production version before releasing app in stores.

Bundle ID Example:

Environment	Bundle ID
Production	`com.myapp`
Development/Testing	`com.myapp.dev`

App Registration Steps

Platform Configuration

How to Register Development App

Registration Procedure

Navigate to Apps: In Singular platform, go to Settings → Apps and click Add New App
Enter App Name: Enter app name for development app (recommend using Bundle ID for clarity)
Select Platform: Select OS corresponding to app platform (iOS or Android)
Configure Bundle ID: Select Bundle ID option and enter development version of Bundle Identifier, then save app
iOS Only - Advanced Settings: After saving app, click arrow next to app name to view details
- Toggle Show Advanced Settings option
- Add Team ID (required for Universal Links)
- Add Scheme (required for deep linking)

Post-Development Updates

After finishing development and testing:

Update Bundle ID: Change Bundle ID to production version in app configuration
Production App Setup: Marketing team adds production app following App Configuration FAQ instructions

Important: Ensure Bundle ID updated to production value before releasing app to App Store or Play Store. Mismatched Bundle IDs prevent proper attribution and tracking.

Step 3: Create Link Domain

Establish custom domain for Singular tracking links enabling branded campaign URLs and deep link functionality.

Link Domain Structure

Singular Link Format

Singular Links (Singular tracking links) follow standardized structure with custom subdomain:

https://[SUBDOMAIN].sng.link/[PARAMETERS]

Example: For app called "Jewel Rush", create domain jewelrush.sng.link enabling tracking links with structure:

https://jewelrush.sng.link/[PARAMETERS]

Domain Strategy

Single vs Multiple Domains

Organizations can use single domain for all links or create multiple domains for different purposes (apps, brands, campaigns, etc.).

Requirement: At least one domain required before using Singular Tracking Links. Marketing team should participate in domain selection as it appears in marketing campaigns and user-facing materials.

Domain Use Cases:

Single Domain: One domain for all tracking links across apps and campaigns
App-Specific: Separate domain per app for brand clarity
Campaign-Specific: Different domains for different campaign types
Geographic: Regional domains for localized campaigns

iOS Domain Configuration

Associated Domains Setup

When integrating Singular SDK in iOS apps, add link domain in Xcode Associated Domain Settings for Universal Links support.

Associated Domain Format:

applinks:[DOMAIN].sng.link

Example:

applinks:jewelrush.sng.link

Additional Resources: For complete domain setup and configuration instructions, see Singular Links Prerequisites.

Step 4: Plan Integration Testing

Validate SDK/S2S integration functionality before releasing app using Singular's testing tools and verification procedures.

Testing Strategy

Testing Phases

Comprehensive testing occurs in two phases: during implementation for real-time validation and after implementation for complete integration verification.

Testing During Implementation

Real-Time Validation Tools

Test features as implemented using real-time validation tools providing immediate feedback.

Testing Console

Use Testing Console to manually test different SDK features in real-time as implemented.

Testing Console Benefits:

Real-Time Feedback: Immediate validation of SDK calls and data transmission
Feature-by-Feature: Test individual features incrementally during development
Debug Support: Identify configuration issues and data problems immediately
Session Tracking: Verify session initialization and event tracking

Third-Party Debugging Tools

Alternative testing approach using proxy tools for traffic inspection and validation.

Charles Proxy Setup:

Install Charles Proxy or similar network inspection tool
Enable SSL proxy for HTTPS traffic inspection
Verify Singular data triggered at correct time with correct parameters
Validate API endpoint calls and response codes

Testing After Implementation

Comprehensive Validation Tools

After completing implementation, use automated and manual tools for complete integration verification.

SDK Audit Report

Run SDK audit report to automatically identify integration issues and receive recommended solutions.

Audit Report Features:

Automatic Detection: Identifies missing or misconfigured SDK features
Best Practice Validation: Verifies implementation against Singular recommendations
Actionable Recommendations: Provides specific solutions for identified issues
Comprehensive Coverage: Checks all SDK features and configurations

Export Logs Verification

Download user-level data using Export Logs page to review all data successfully transmitted from app to Singular.

Export Logs Details:

Data Format: CSV file with complete user-level data
Timing: Approximately 30 minutes before data available
Validation: Verify events, sessions, and attribution data
Debugging: Identify missing events or incorrect data

Deep Link Testing

Test deep links following instructions in How to Test Your Singular SDK Integration.

Deep Link Test Cases:

Universal Links: Test iOS Universal Links and Android App Links
Custom Schemes: Verify custom URL scheme handling
Deferred Deep Links: Test links clicked before app installation
Campaign Parameters: Validate parameter passing and attribution

Attribution Verification

Use Attribution Details API to query device attribution details after testing. Attribution data available approximately 4-6 minutes after event.

Learn how to verify attribution using Attribution Details Endpoint.

Attribution Verification Steps:

Execute Test: Install app and complete test user journey
Wait for Processing: Allow 4-6 minutes for attribution processing
Query API: Use Attribution Details API with device identifier
Verify Results: Confirm attribution to correct campaign and source

Additional Testing Resources

Complete Testing Guide

For comprehensive testing procedures, best practices, and troubleshooting, see How to Test Your Singular SDK Integration.

Testing Checklist:

Testing Console validates real-time SDK calls
SDK Audit Report confirms complete integration
Export Logs verify data transmission
Deep links function correctly across scenarios
Attribution matches expected campaign source
Events tracked with correct names and attributes
Revenue events capture amount and currency

Next Steps

After completing prerequisites, proceed with platform-specific SDK integration or S2S implementation.

SDK Integration Guides

Additional Resources

App Configuration FAQ - Production app setup and configuration
Singular Links Prerequisites - Link domain and deep linking setup
Standard Events Reference - Complete standard event and attribute list
Testing SDK Integration - Complete testing procedures and validation