SDK Documentation

Table of Contents

• Introduction
• Features
• Authentication API
• Platforms
  • Android
    • Initialize
    • Mediation / Ads
    • Payment Service
    • User Retention
    • Attribution
    • Notification
  • iOS
    • Initialize
    • Ad Implementation
    • Retention & Notification
• Common Technical Issues
• SDK Implementation Guidelines

Introduction

Welcome to the Locallify SDK Documentation. This SDK enables developers to integrate key features such as in-app advertising, localized payments, retention management, and attribution tracking seamlessly into their mobile applications. This documentation guides you through the implementation process for both Android and iOS platforms.

⚠️ Note: The SDK is currently under development. Expect regular updates with new features and enhancements.

Features

The Locallify SDK offers a comprehensive suite of features designed to enhance mobile app functionality and market performance, particularly within the Iranian market. Here’s how each feature can significantly benefit developers:

Localized Ads

Localized Ads: Our SDK provides robust ad management tools that allow developers to display culturally-relevant ads tailored to the Iranian audience. By leveraging local cultural insights and consumer behavior, these ads achieve higher engagement rates and significantly improve conversion. The SDK supports various ad formats including banner, interstitial, and video ads, ensuring that developers can utilize the most effective strategies for their specific applications.

In-App Payments

In-App Payments: Facilitate Rial-based transactions with ease using our SDK’s seamless integration process. The payment gateway is designed with security and efficiency in mind, offering a smooth transaction experience for users. This feature supports a wide range of payment methods popular in Iran, including local credit cards, mobile wallets, and direct carrier billing, making it easier for users to make purchases within your app, thereby boosting your revenue potential.

Retention Management

Retention Management: Keep your users coming back! Our SDK includes advanced analytics and retention tools that help developers understand user behavior, identify trends, and implement strategies to increase user engagement and retention. Features like custom event tracking, cohort analysis, and automated push notifications enable developers to create personalized user experiences and maintain a vibrant user base.

Attribution Management

Attribution Management: Gain clear insights into which marketing campaigns and channels are driving app installations and user engagement. Our attribution tools allow developers to track and analyze the performance of various advertising sources in real-time, adjust marketing spend more effectively, and optimize ROI. This feature is crucial for developers looking to understand their market reach and refine their marketing strategies based on solid data.

💡 Pro Tip: Integrating these features can not only enhance your app’s performance but also provide invaluable insights into user preferences and behavior, paving the way for sustained growth and success in the competitive Iranian app market.

Authentication API

The Authentication API provides secure user verification processes. Due to the sensitive nature of authentication data and associated legal and compliance issues, general access to this API is restricted.

⚠️ Important: To obtain a unique verification token for your project, please contact tech@locallify.com. Access to the API requires prior approval and appropriate security credentials.

Integrating the Authentication API

Once you have received your API credentials, you can integrate the Authentication API as follows:

import LocallifyAuth

class AuthenticationManager {

    func authenticateUser(username: String, password: String) {
        let credentials = Credentials(username: username, password: password)
        LocallifyAuth.authenticate(credentials: credentials) { result in
            switch result {
            case .success(let user):
                print("Authentication successful for user: \(user.id)")
            case .failure(let error):
                print("Authentication failed with error: \(error.localizedDescription)")
            }
        }
    }
}

Handling Authentication Responses

struct Credentials {
    var username: String
    var password: String
}

enum AuthenticationResult {
    case success(User)
    case failure(Error)
}

struct User {
    var id: String
    var token: String
}

// Example Usage
let authManager = AuthenticationManager()
authManager.authenticateUser(username: "exampleUser", password: "examplePass")

💡 Tip: Always use HTTPS for all communications involving authentication to ensure data security. Do not transmit sensitive information over unencrypted channels.

Error Handling and Security Best Practices

Properly handle errors during authentication and implement best security practices:

func handleAuthenticationError(error: Error) {
    // Log error for debugging, avoid showing detailed errors to the user
    print("Error during authentication: \(error.localizedDescription)")
}

// Ensure sensitive user data is encrypted and stored securely

⚠️ Warning: Never log or store user passwords in plain text. Ensure all password handling adheres to current security standards and legal regulations.

Platforms Overview

The Locallify SDK is designed to support multiple platforms, enabling developers to integrate our services into their applications regardless of the development environment. Below, you will find detailed documentation tailored to each supported platform, ensuring that you can fully leverage the capabilities of the SDK whether you are developing for Android or iOS.

This section serves as your gateway to specific guidance and code examples that will help you implement the Locallify SDK in your preferred platform:

• Android SDK Implementation: Explore how to integrate the SDK into Android applications, including setup instructions, feature integration, and code examples for Java and Kotlin.
• iOS SDK Implementation: Discover how to incorporate the SDK into iOS applications with detailed guidance on setup, feature integration, and Swift code examples.

Choose your platform to get started with the Locallify SDK:

💡 Tip: Familiarize yourself with the common features and functionalities offered by the Locallify SDK in the Features section to better understand how they can enhance your application across different platforms.

Android Integration

Follow the steps below to implement the SDK in your Android project. The Locallify SDK supports both Java and Kotlin.

Initialize

To begin using the Locallify SDK, you need to initialize it with your API key.

Java Implementation

import com.locallify.sdk.Locallify;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Initialize SDK
        Locallify.initialize(this, "YOUR_API_KEY");
        System.out.println("SDK Initialized Successfully!");
    }
}

Kotlin Implementation

import com.locallify.sdk.Locallify

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

        // Initialize SDK
        Locallify.initialize(this, "YOUR_API_KEY")
        println("SDK Initialized Successfully!")
    }
}

⚠️ Note: Replace “YOUR_API_KEY” with the key provided from your Locallify account.

Mediation / Ads

The Locallify SDK supports ad mediation to maximize ad revenue through multiple networks.

Java Implementation

Step 1: Add the SDK Dependency

implementation 'com.locallify.sdk:ads:1.0.0'

Step 2: Load Banner Ads

import com.locallify.sdk.ads.AdMediationManager;
import com.locallify.sdk.ads.AdType;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Initialize Ad Mediation
        AdMediationManager mediationManager = new AdMediationManager(this, "AD_UNIT_ID");

        // Load a Banner Ad
        mediationManager.loadAd(AdType.BANNER, findViewById(R.id.bannerAdView));
    }
}

Step 3: Add Ad View to Layout

<com.locallify.sdk.ads.BannerAdView
    android:id="@+id/bannerAdView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

Kotlin Implementation

import com.locallify.sdk.ads.AdMediationManager
import com.locallify.sdk.ads.AdType

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

        // Initialize Ad Mediation
        val mediationManager = AdMediationManager(this, "AD_UNIT_ID")

        // Load a Banner Ad
        mediationManager.loadAd(AdType.BANNER, findViewById(R.id.bannerAdView))
    }
}

⚠️ Warning: Ensure your Ad Unit ID is correctly set up on the Locallify dashboard.

Payment Service

Enable seamless Rial-based payments with Locallify’s Payment Service.

Java Implementation

import com.locallify.sdk.payments.PaymentManager;
import com.locallify.sdk.payments.PaymentCallback;

public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Payment Service Initialization
        PaymentManager paymentManager = new PaymentManager();

        // Process Payment
        paymentManager.processPayment("USER_ID", 10000, new PaymentCallback() {
            @Override
            public void onSuccess(String transactionId) {
                System.out.println("Payment successful: " + transactionId);
            }

            @Override
            public void onFailure(String error) {
                System.out.println("Payment failed: " + error);
            }
        });
    }
}

Kotlin Implementation

import com.locallify.sdk.payments.PaymentManager
import com.locallify.sdk.payments.PaymentCallback

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

        // Payment Service Initialization
        val paymentManager = PaymentManager()

        // Process Payment
        paymentManager.processPayment("USER_ID", 10000, object : PaymentCallback {
            override fun onSuccess(transactionId: String) {
                println("Payment successful: $transactionId")
            }

            override fun onFailure(error: String) {
                println("Payment failed: $error")
            }
        })
    }
}

💡 Tip: The amount parameter is specified in “Rials”.

User Retention

Optimize user retention with Locallify SDK’s comprehensive analytics and targeted engagement strategies.

Java Implementation

Step 1: Setup Retention Tracker

import com.locallify.sdk.retention.RetentionManager;
import com.locallify.sdk.retention.RetentionEvent;

public class MainActivity extends AppCompatActivity {
    private RetentionManager retentionManager;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Initialize Retention Manager
        retentionManager = new RetentionManager(this);

        // Track app launch event
        retentionManager.trackEvent(RetentionEvent.APP_LAUNCH);
    }

    @Override
    protected void onResume() {
        super.onResume();
        // Track user return
        retentionManager.trackEvent(RetentionEvent.USER_RETURN);
    }
}

Step 2: Track User Interactions

public void onUserInteraction() {
    // Track custom user interaction
    retentionManager.trackEvent(RetentionEvent.CUSTOM_INTERACTION);
}

Step 3: Analyze Retention Data

public void analyzeData() {
    retentionManager.getRetentionMetrics(new RetentionManager.RetentionCallback() {
        @Override
        public void onResult(RetentionMetrics metrics) {
            System.out.println("Retention Rate: " + metrics.getRetentionRate());
        }

        @Override
        public void onError(String error) {
            System.err.println("Error fetching retention data: " + error);
        }
    });
}

Kotlin Implementation

import com.locallify.sdk.retention.RetentionManager
import com.locallify.sdk.retention.RetentionEvent

class MainActivity : AppCompatActivity() {
    private lateinit var retentionManager: RetentionManager

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

        // Initialize Retention Manager
        retentionManager = RetentionManager(this)

        // Track app launch event
        retentionManager.trackEvent(RetentionEvent.APP_LAUNCH)
    }

    override fun onResume() {
        super.onResume()
        // Track user return
        retentionManager.trackEvent(RetentionEvent.USER_RETURN)
    }

    fun onUserInteraction() {
        // Track custom user interaction
        retentionManager.trackEvent(RetentionEvent.CUSTOM_INTERACTION)
    }

    fun analyzeData() {
        retentionManager.getRetentionMetrics { metrics, error ->
            metrics?.let {
                println("Retention Rate: ${it.retentionRate}")
            }
            error?.let {
                println("Error fetching retention data: $it")
            }
        }
    }
}

💡 Tip: Regularly analyze retention metrics to identify trends and areas for improvement.

Attribution

Track and analyze the sources of app installs and key events to optimize your ad campaigns and measure user acquisition.

Java Implementation

Step 1: Initialize Attribution Manager

import com.locallify.sdk.attribution.AttributionManager;
import com.locallify.sdk.attribution.AttributionCallback;
import com.locallify.sdk.attribution.AttributionData;

public class MainActivity extends AppCompatActivity {
    private AttributionManager attributionManager;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Initialize Attribution Manager
        attributionManager = new AttributionManager(this, "YOUR_TRACKING_ID");

        // Fetch attribution data
        attributionManager.fetchAttributionData(new AttributionCallback() {
            @Override
            public void onSuccess(AttributionData data) {
                System.out.println("Install Source: " + data.getSource());
                System.out.println("Campaign: " + data.getCampaign());
            }

            @Override
            public void onFailure(String error) {
                System.err.println("Attribution fetch error: " + error);
            }
        });
    }
}

Step 2: Track Custom Events

public void trackEvent(String eventName) {
    attributionManager.trackEvent(eventName);
    System.out.println("Event tracked: " + eventName);
}

Kotlin Implementation

import com.locallify.sdk.attribution.AttributionManager
import com.locallify.sdk.attribution.AttributionCallback
import com.locallify.sdk.attribution.AttributionData

class MainActivity : AppCompatActivity() {
    private lateinit var attributionManager: AttributionManager

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

        // Initialize Attribution Manager
        attributionManager = AttributionManager(this, "YOUR_TRACKING_ID")

        // Fetch Attribution Data
        attributionManager.fetchAttributionData(object : AttributionCallback {
            override fun onSuccess(data: AttributionData) {
                println("Install Source: ${data.source}")
                println("Campaign: ${data.campaign}")
            }

            override fun onFailure(error: String) {
                println("Attribution fetch error: $error")
            }
        })
    }

    fun trackEvent(eventName: String) {
        attributionManager.trackEvent(eventName)
        println("Event tracked: $eventName")
    }
}

⚠️ Warning: Ensure you configure your tracking ID correctly. Misconfigured tracking may result in missing attribution data.

Notification

Send targeted push notifications to engage your users and manage user interactions effectively.

Java Implementation

Step 1: Initialize Notification Service

import com.locallify.sdk.notifications.NotificationManager;
import com.locallify.sdk.notifications.NotificationCallback;

public class MainActivity extends AppCompatActivity {
    private NotificationManager notificationManager;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Initialize Notification Service
        notificationManager = new NotificationManager(this, "YOUR_API_KEY");
        notificationManager.registerDevice(new NotificationCallback() {
            @Override
            public void onSuccess() {
                System.out.println("Device registered for notifications.");
            }

            @Override
            public void onFailure(String error) {
                System.err.println("Notification registration error: " + error);
            }
        });
    }
}

Step 2: Handle Notification Events

@Override
public void onNewIntent(Intent intent) {
    super.onNewIntent(intent);

    // Handle incoming notification clicks
    notificationManager.handleNotificationIntent(intent);
    System.out.println("Notification clicked!");
}

Kotlin Implementation

import com.locallify.sdk.notifications.NotificationManager
import com.locallify.sdk.notifications.NotificationCallback

class MainActivity : AppCompatActivity() {
    private lateinit var notificationManager: NotificationManager

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

        // Initialize Notification Service
        notificationManager = NotificationManager(this, "YOUR_API_KEY")
        notificationManager.registerDevice(object : NotificationCallback {
            override fun onSuccess() {
                println("Device registered for notifications.")
            }

            override fun onFailure(error: String) {
                println("Notification registration error: $error")
            }
        })
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)

        // Handle notification clicks
        notificationManager.handleNotificationIntent(intent)
        println("Notification clicked!")
    }
}

💡 Tip: Test notifications thoroughly on real devices to ensure proper delivery and user interaction handling.

iOS Integration

Follow the steps below to integrate the SDK in an iOS application using Swift.

Initialize

Proper initialization is crucial for leveraging all features of the Locallify SDK on iOS.

import LocallifySDK

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize the SDK
        LocallifySDK.initialize(withAPIKey: "YOUR_API_KEY")
        
        print("Locallify SDK Initialized Successfully")
        return true
    }
}

💡 Tip: Ensure your API key is correct to avoid initialization issues.

Ad Implementation

Implement ads efficiently with Locallify SDK to monetize your iOS apps.

Integrating Banner Ads

import LocallifySDK

class ViewController: UIViewController {

    var adView: LocallifyAdView!

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Initialize Ad View
        adView = LocallifyAdView(adSize: .banner, origin: CGPoint(x: 0, y: 0))
        
        // Load Ad
        adView.loadAd()
        adView.delegate = self
        self.view.addSubview(adView)
    }
}

extension ViewController: LocallifyAdDelegate {
    func adDidReceive() {
        print("Ad loaded successfully")
    }
    
    func adDidFailToLoad(error: Error) {
        print("Failed to load ad: \(error.localizedDescription)")
    }
}

Handling Ad Events

extension ViewController {
    func adViewDidReceiveTap() {
        print("Ad tapped by user")
    }
}

⚠️ Warning: Always test ad integration in different network conditions to ensure robust performance.

Retention & Notification

Maximize user engagement and retention through notifications and analytics.

Configuring Push Notifications

import LocallifySDK
import UserNotifications

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Request Notification Permission
        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, error in
            if granted {
                print("Notification permission granted.")
            } else if let error = error {
                print("Notification permission denied: \(error)")
            }
        }

        // Register for Remote Notifications
        application.registerForRemoteNotifications()

        return true
    }

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Handle successful registration
        LocallifySDK.registerDeviceToken(deviceToken)
    }

    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        // Handle failed registration
        print("Failed to register for remote notifications: \(error.localizedDescription)")
    }
}

💡 Tip: Implement deep linking in notifications to improve user engagement.

Common Technical Issues

Below are common SDK issues and their resolutions, presented in a collapsible format for ease of navigation:

SDK Implementation Guidelines

Ensure a successful and compliant integration of the Locallify SDK into your application with the following guidelines:

Data Privacy Compliance

Adhere to global data privacy laws. Obtain necessary user consents and maintain transparency about data usage.

Network Configurations

Ensure that your network settings allow communications with Locallify servers. Adjust firewall settings accordingly.

Testing Environments

Test the SDK thoroughly in various environments before going live to ensure stability and performance.

Legal Compliance

To use the Locallify SDK, you must agree to our Terms of Use and Privacy Policy.

Stay Updated

We are continuously improving the Locallify SDK to include new features and optimizations. Be sure to check our documentation regularly for updates.

If you encounter any issues or need support, feel free to contact our team at tech@locallify.com.

---