Creating Short Referrer Links

Generate short, shareable referrer links that enable user-to-user attribution and track app installs from organic referrals.

Overview

What Are Short Referrer Links

Short links transform long, parameter-filled Singular Links into compact, secure URLs convenient for sharing via SMS, social media, or in-app invitations.

Create short links dynamically so users can share them with friends to invite them to download and use your app. Each short link tracks the referring user, enabling you to measure viral growth and attribute new installs to specific advocates.

Implementation Requirements

Required Components

Gather these elements before creating a short referrer link:

• Singular Link: A base tracking link that directs users to your app download. See Singular Links FAQ for setup instructions
• Dynamic Parameters: Optional custom parameters to add context to the link. View available options in Tracking Link Parameters
• Referrer Information: Name and ID of the user sharing the link to enable attribution of new installs back to the referrer

SDK Method

createReferrerShortLink

Generate a short referrer link with custom parameters and callback handlers for success and error states.

Method Signature:

+ (void)createReferrerShortLink:(NSString *)baseLink 
                   referrerName:(NSString *)referrerName 
                     referrerId:(NSString *)referrerId 
              passthroughParams:(NSDictionary *)passthroughParams 
              completionHandler:(void(^)(NSString *, NSError *))completionHandler;

Parameters:

• baseLink: The original Singular tracking link URL
• referrerName: Display name of the referring user
• referrerId: Unique identifier for the referring user
• passthroughParams: NSDictionary containing additional dynamic parameters (optional)
• completionHandler: Callback block with short link string and error parameters

Usage Example

Create a short link with custom parameters and implement sharing logic in the completion handler.

// Define your Singular tracking link as the base link
let referrerBaseLink = "https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3"

// Get referrer information from user input
let referrerID = referrerIDField.text ?? "unknown_user"
let referrerName = referrerNameField.text ?? "Anonymous"

// Add custom passthrough parameters
let passthroughParams: [String: Any] = [
    "channel": "sms",
    "campaign_id": "summer_promo_2025",
    "referral_type": "friend_invite"
]

// Generate the short referrer link
Singular.createReferrerShortLink(
    referrerBaseLink,
    referrerName: referrerName,
    referrerId: referrerID,
    passthroughParams: passthroughParams
) { shortLink, error in
    
    if let error = error {
        // Handle error - retry or show user feedback
        print("Error creating short link: \(error.localizedDescription)")
        
        // Show error message to user
        let alert = UIAlertController(
            title: "Error",
            message: "Failed to create share link. Please try again.",
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        self.present(alert, animated: true)
        return
    }
    
    if let shortLink = shortLink, !shortLink.isEmpty {
        // Share the short link via iOS Activity Controller
        let shareText = "Join me on this awesome app! \(shortLink)"
        let activityVC = UIActivityViewController(
            activityItems: [shareText],
            applicationActivities: nil
        )
        
        // For iPad: set popover presentation controller
        if let popover = activityVC.popoverPresentationController {
            popover.sourceView = self.view
            popover.sourceRect = CGRect(x: self.view.bounds.midX, 
                                       y: self.view.bounds.midY, 
                                       width: 0, 
                                       height: 0)
            popover.permittedArrowDirections = []
        }
        
        self.present(activityVC, animated: true)
    }
}

// Define your Singular tracking link as the base link
NSString *referrerBaseLink = @"https://yourdomain.sng.link/Csfge/aknl?_dl=myscheme%3A%2F%2Fmydeeplink/referrer&_smtype=3";

// Get referrer information from user input
NSString *referrerID = self.referrerIDField.text ?: @"unknown_user";
NSString *referrerName = self.referrerNameField.text ?: @"Anonymous";

// Add custom passthrough parameters
NSDictionary *passthroughParams = @{
    @"channel": @"sms",
    @"campaign_id": @"summer_promo_2025",
    @"referral_type": @"friend_invite"
};

// Generate the short referrer link
[Singular createReferrerShortLink:referrerBaseLink
                     referrerName:referrerName
                       referrerId:referrerID
                passthroughParams:passthroughParams
                completionHandler:^(NSString *shortLink, NSError *error) {
    
    if (error) {
        // Handle error - retry or show user feedback
        NSLog(@"Error creating short link: %@", error.localizedDescription);
        
        // Show error message to user
        UIAlertController *alert = [UIAlertController 
            alertControllerWithTitle:@"Error" 
            message:@"Failed to create share link. Please try again." 
            preferredStyle:UIAlertControllerStyleAlert];
        [alert addAction:[UIAlertAction actionWithTitle:@"OK" 
            style:UIAlertActionStyleDefault 
            handler:nil]];
        [self presentViewController:alert animated:YES completion:nil];
        return;
    }
    
    if (shortLink && ![shortLink isEqualToString:@""]) {
        // Share the short link via iOS Activity Controller
        NSString *shareText = [NSString stringWithFormat:@"Join me on this awesome app! %@", shortLink];
        UIActivityViewController *activityVC = [[UIActivityViewController alloc] 
            initWithActivityItems:@[shareText] 
            applicationActivities:nil];
        
        // For iPad: set popover presentation controller
        if (activityVC.popoverPresentationController) {
            activityVC.popoverPresentationController.sourceView = self.view;
            activityVC.popoverPresentationController.sourceRect = CGRectMake(
                CGRectGetMidX(self.view.bounds),
                CGRectGetMidY(self.view.bounds),
                0, 0
            );
            activityVC.popoverPresentationController.permittedArrowDirections = 0;
        }
        
        [self presentViewController:activityVC animated:YES completion:nil];
    }
}];

Implementation Best Practices

Error Handling

Implement robust error handling in the completion handler to manage network failures, invalid parameters, or server issues.

• Retry Logic: Implement exponential backoff for transient network errors
• User Feedback: Display clear error messages when link creation fails
• Fallback Option: Provide alternative sharing methods (e.g., share the full Singular Link if short link creation fails)
• Validation: Verify parameters before calling createReferrerShortLink to catch issues early

Tracking and Analytics

Leverage referrer information to build viral loops and measure organic growth.

Link Expiration

Plan for the 30-day link lifecycle in your sharing strategy.

Common Use Cases

In-App Referral Programs

Enable users to invite friends directly from your app with personalized referral links.

• Reward System: Track referrals and reward users for successful friend signups
• Social Sharing: Integrate with iOS Activity Controller for Messages, Mail, and social media
• Personal Invites: Include referrer name in the shared message for personalization

User-Generated Content

Create shareable links when users generate content they want to share with others.

• Content Attribution: Track which content drives the most app installs
• Creator Recognition: Attribute new users to content creators for gamification
• Campaign Tagging: Add dynamic parameters based on content type or category

Event Invitations

Generate unique links for event invitations that track which attendees bring new users.

• Event Context: Include event ID and details in link parameters
• Attendee Tracking: Measure viral spread from event to event
• Network Effects: Identify events with the highest conversion rates