Surfboard Gap SDK Example

Example Android application demonstrating the integration and usage of the Surfboard Gap SDK

Overview

This is a complete example Android application that demonstrates how to integrate and use the Surfboard Gap SDK for payment processing with terminal integration and haptic feedback support. The application showcases the SDK's capabilities and serves as a reference implementation for developers.

Prerequisites

Before running this example application, ensure you have:

• Android Studio: Version 4.1 or higher
• Minimum SDK Version: API level 29 (Android 10.0)
• Target SDK Version: API level 35
• Compile SDK Version: API level 35
• Android Gradle Plugin: Version 8.10.0 or higher
• Kotlin: Version 2.0.21 or higher
• Java: Version 11
• Valid Surfboard Gap SDK License: Contact your Surfboard representative

Project Structure

Surfboard Gap SDK Example/
├── app/
│   ├── libs/
│   │   └── surfboard/
│   │       ├── gap_sdk.aar                 # Main SDK library
│   │       └── additional/                 # Additional SDK components
│   ├── src/main/java/com/surfboard/gapsdk/androidgapexample/
│   │   ├── MainActivity.kt                 # Main activity
│   │   ├── GapSdkHandler.kt                # SDK interaction handler
│   │   ├── ButtonLayoutManager.kt          # UI layout management
│   │   ├── LogAdapter.kt                   # Logging adapter
│   │   ├── LoggerWidget.kt                 # Logger widget
│   │   ├── constants/                      # Application constants
│   │   ├── models/                         # Data models
│   │   ├── network/                        # Network layer
│   │   └── ui/theme/                       # Jetpack Compose theme
│   ├── src/main/res/                       # Android resources
│   └── build.gradle.kts                    # App module build configuration
├── gradle/
│   └── libs.versions.toml                  # Version catalog
├── settings.gradle.kts                     # Project settings
└── build.gradle.kts                        # Root build configuration

Technology Stack

This example application uses:

• Jetpack Compose: Modern Android UI toolkit
• Kotlin: Primary programming language
• Surfboard Gap SDK: Payment processing and terminal integration
• OkHttp: HTTP client for network operations
• RxJava: Reactive programming
• Gson: JSON serialization/deserialization
• Arrow: Functional programming utilities
• Android Security Crypto: Cryptographic operations

Configuration Details

Gradle Configuration

Settings Configuration (settings.gradle.kts)

The project is configured with repositories for SDK access:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        mavenLocal {
            url = URI("file:" + rootProject.projectDir.path + "/app/libs/surfboard/additional")
        }
        flatDir {
            dirs("app/libs/surfboard")
        }
    }
}

rootProject.name = "Surfboard Gap SDK Example"

Version Catalog (gradle/libs.versions.toml)

Key dependency versions:

[versions]
agp = "8.10.0"
kotlin = "2.0.21"
arrowCore = "2.1.2"
okhttp = "4.12.0"
rxjava = "3.1.10"
gson = "2.13.1"
terminalLib = "1.10.4-100702"
hapticsLibDebug = "1.2.0"
securityCrypto = "1.1.0-alpha06"

App Configuration (app/build.gradle.kts)

SDK Configuration

android {
    namespace = "com.exampleapp.softpos.sampleapplication"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.exampleapp.softpos.sampleapplication"
        minSdk = 29
        targetSdk = 35
        multiDexEnabled = true  // MANDATORY - Required for Surfboard Gap SDK
    }

    buildFeatures {
        buildConfig = true
        viewBinding = true
        compose = true
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

MultiDex Configuration

🚨 IMPORTANT: MultiDex is MANDATORY for the Surfboard Gap SDK due to the large number of methods in the SDK and its dependencies.

defaultConfig {
    multiDexEnabled = true
}

Dependencies

Mandatory Surfboard Gap SDK Dependencies

dependencies {
    // Core SDK
    implementation(files("libs/surfboard/gap_sdk.aar"))

    // Required dependencies
    implementation(libs.okhttp)                    // HTTP client
    implementation(libs.arrow.core)               // Functional programming
    implementation(libs.gson)                     // JSON processing
    implementation(libs.rxjava)                   // Reactive programming
    implementation(libs.androidx.security.crypto) // Security/encryption

    // Terminal communication (MANDATORY)
    debugImplementation(libs.terminal.lib.debug)
    releaseImplementation(libs.terminal.lib)

    // Haptic feedback (MANDATORY)
    debugImplementation(libs.haptics.lib.debug)
    releaseImplementation(libs.haptics.lib.release)
}

Dependency Requirements

Dependency	Purpose	Status
gap_sdk.aar	Core SDK functionality	✅ Mandatory
okhttp	Network communication	✅ Mandatory
arrow-core	Functional programming utilities	✅ Mandatory
gson	JSON serialization	✅ Mandatory
rxjava	Reactive programming	✅ Mandatory
security-crypto	Cryptographic operations	✅ Mandatory
terminal-lib	Terminal communication	✅ Mandatory
haptics-lib	Haptic feedback	✅ Mandatory

Android Manifest Configuration

Required Permissions and Features

Add these to your AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Hardware Features -->
    <uses-feature
        android:name="android.hardware.camera"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.nfc"
        android:required="true"/>

    <!-- Permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.NFC" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme">

        <!-- Your activities -->

    </application>
</manifest>

Permission Explanations

• NFC: Required for terminal communication
• Camera: Optional for barcode/QR code scanning
• Audio: Required for audio feedback during transactions
• Internet/Network: Required for API communication

ProGuard/R8 Configuration (Optional)

If you choose to enable ProGuard/R8 for code obfuscation in release builds, ensure you preserve Surfboard SDK classes by adding these rules to proguard-rules.pro:

# Surfboard Gap SDK Protection Rules
-keep class com.surfboard.** { *; }
-keepclassmembers class com.surfboard.** { *; }

# Terminal library classes
-keep class com.mypinpad.** { *; }

# Haptics library classes
-keep class com.haptics.** { *; }

# Supporting libraries
-keep class okhttp3.** { *; }
-keep class rx.** { *; }
-keep class arrow.** { *; }
-keep class com.google.gson.** { *; }

Note: ProGuard/R8 configuration is optional. Only add these rules if you plan to enable code minification in your release builds.

Running the Example

1. Clone and Setup

git clone <repository-url>
cd AndroidGapExample

2. Open in Android Studio

1. Open Android Studio
2. Select "Open an existing project"
3. Navigate to the project directory
4. Wait for Gradle sync to complete

3. Configure Build Variants

The project includes specific configurations for debug and release builds with Surfboard-specific BuildConfig fields:

• terminalId
• merchantId
• storeId
• connectionBlob

4. Build and Run

# Clean and build
./gradlew clean build

# Install on connected device
./gradlew installDebug

# Or use Android Studio's Run button

Build Configuration

BuildConfig Fields

The example includes Surfboard-specific configuration fields:

buildTypes {
    release {
        buildConfigField("String", "terminalId", "\"SURFBOARD_TERMINAL_ID\"")
        buildConfigField("String", "merchantId", "\"SURFBOARD_MERCHANT_ID\"")
        buildConfigField("String", "storeId", "\"SURFBOARD_STORE_ID\"")
        buildConfigField("String", "connectionBlob", "\"SURFBOARD_ENCRYPTED_BLOB\"")
    }
    debug {
        buildConfigField("String", "terminalId", "\"SURFBOARD_TERMINAL_ID\"")
        buildConfigField("String", "merchantId", "\"SURFBOARD_MERCHANT_ID\"")
        buildConfigField("String", "storeId", "\"SURFBOARD_STORE_ID\"")
        buildConfigField("String", "connectionBlob", "\"SURFBOARD_ENCRYPTED_BLOB\"")
    }
}

Example Features

This application demonstrates:

• SDK Integration: Complete setup and initialization
• Payment Processing: Transaction handling examples
• Terminal Communication: Device connectivity
• Haptic Feedback: User interaction feedback
• Error Handling: Comprehensive error management
• Logging: Detailed operation logging
• UI Components: Modern Jetpack Compose interface

Package Structure

com.exampleapp.softpos.sampleapplication/
├── MainActivity.kt              # Main application entry point
├── GapSdkHandler.kt            # Central SDK interaction handler
├── ButtonLayoutManager.kt       # UI layout management
├── LogAdapter.kt               # Logging functionality
├── LoggerWidget.kt             # Log display widget
├── constants/
│   └── ButtonsInPage.kt        # UI constants
├── models/
│   ├── ButtonCategory.kt       # Button category model
│   ├── LogEntry.kt             # Log entry model
│   └── OnClickListeners.kt     # Click listener models
├── network/
│   └── OrderApiService.kt      # Network API service
└── ui/theme/
    ├── Color.kt                # Color definitions
    ├── Theme.kt                # Theme configuration
    └── Type.kt                 # Typography definitions

Version Information

• Project Version: 1.0
• SDK Version: As defined in libs.versions.toml
• Last Updated: 2025

---

For detailed SDK usage documentation and integration guides, please refer to the official Surfboard Gap SDK documentation provided by your Surfboard representative.