Integrating ScratchCard Pro with Unity and Unreal Engine
ScratchCard Pro is a cross-platform SDK that enables interactive scratch-card mechanics, randomized prizes, and analytics for games and apps. This article explains how to integrate ScratchCard Pro into both Unity and Unreal Engine projects, including setup, example code, event handling, performance tips, monetization strategies, testing, and troubleshooting.
What ScratchCard Pro provides
- A native engine-optimized scratch mask with configurable brush sizes, shapes, and smoothing.
- Randomization and prize management, with server-side verification.
- Analytics hooks (impressions, completes, prize reveals).
- Rewards flow helpers (redeem APIs, IAP and ad integrations).
- Lightweight native bindings for Unity (C# wrapper) and Unreal (C++/Blueprints).
Preparation
1. Obtain the SDK: Download the Unity package and Unreal plugin from your provider portal. You should also receive API keys and access to server-side endpoints for prize validation.
2. Platform targets: Ensure you have the correct plugin builds for Android (ARMv7/ARM64), iOS (arm64), Windows, and macOS as needed.
3. Prerequisites: Unity 2019.4+ (recommended 2020+), Unreal Engine 4.26+ or 5.0+. For iOS builds, an Apple developer account and proper entitlements are required. For Android, configure the minimum SDK and ABI settings.
Integration steps — Unity (overview)
1. Import package: In Unity, Assets → Import Package → Custom Package and select ScratchCardPro.unitypackage. This adds a ScratchCardPro folder with prefabs, scripts, and the native libraries (Plugins/Android, Plugins/iOS, etc).
2. Initialize SDK: Add initialization code in a startup scene or singleton manager. Use the provided API key and environment.
Example (C#):
using ScratchCardPro;
public class ScratchManager : MonoBehaviour
{
void Start()
{
ScratchCardProSDK.Initialize("YOUR_API_KEY");
ScratchCardProSDK.OnInitialized += OnInitialized;
ScratchCardProSDK.OnError += OnError;
}
void OnInitialized()
{
Debug.Log("ScratchCard Pro initialized");
}
void OnError(string message)
{
Debug.LogError("ScratchCardPro error: " + message);
}
}
3. Create a scratch card: Drag the provided ScratchCard prefab into your scene. Configure:
- ScratchMaskTexture: a grayscale or alpha mask controlling the reveal.
- BrushTexture and brush size.
- PrizeImage or Content to reveal.
4. Hook events: Subscribe to OnScratchStart, OnScratchProgress, OnScratchComplete to update UI, analytics, or trigger prize validation.
Example event handlers:
void OnEnable()
{
ScratchCard.OnScratchStart += HandleStart;
ScratchCard.OnScratchProgress += HandleProgress;
ScratchCard.OnScratchComplete += HandleComplete;
}
void HandleComplete()
{
// Call server to validate prize
StartCoroutine(ValidatePrizeCoroutine());
}
5. Platform builds: For iOS, add the required frameworks and modify Info.plist if the SDK requires network access keys. For Android, ensure the manifest merges the SDK activity and permissions.
Integration steps — Unreal Engine (overview)
1. Install plugin: Copy the ScratchCardPro plugin folder into your Unreal project’s Plugins directory and enable it in Edit → Plugins. Restart the editor.
2. Initialize in C++ or Blueprints: The plugin exposes a manager class and Blueprint nodes.
C++ Initialization (pseudo):
#include "ScratchCardProModule.h"
void AMyGameMode::BeginPlay()
{
IScratchCardProModule::Get().Initialize("YOUR_API_KEY");
IScratchCardProModule::Get().OnInitialized.AddRaw(this, &AMyGameMode::OnInitialized);
}
3. Create a scratch widget: The plugin includes a UMG widget (ScratchCardWidget). Add it to your HUD or UI. Configure mask, brush, and reveal target in the widget properties.
4. Blueprints: Use nodes like InitializeScratchCard, OnScratchComplete, GetScratchProgress to integrate without C++.
5. Server-side validation: Hook the OnScratchComplete event to call your backend via HTTP (Unreal’s HTTP module or a Blueprint HTTP request).
Cross-engine common concerns
- Randomness and server validation: For monetized prizes or valuable items, use server-side drawing and sign the results. Client-side randomization is convenient but insecure.
- State persistence: Save scratch state progress to allow users to resume. Both SDKs expose APIs to export mask state (binary blob) and restore it.
- Localization: Provide localized prize text and images. Use localized assets or fetch content at runtime from your server.
- Analytics: Send scratch events (start, progress thresholds, complete, reveal) to your analytics service (Unity Analytics, Unreal Insights, or third-party).
- Security: Obfuscate API keys in client builds and use short-lived tokens or device-based signatures. Always validate reward claims server-side.
Performance tips
- Use appropriately sized mask textures. A 2048x2048 mask for full-screen are usually enough; higher sizes increase memory and CPU for brush operations.
- Limit brush alpha/softness calculations if you need many simultaneous scratchers (e.g., in multiplayer lobbies).
- Pool ScratchCard objects for repeated usage instead of instantiating/destroying frequently.
- On mobile, use the GPU-accelerated shader path if provided by ScratchCard Pro to offload masking to the GPU.
Monetization and UX patterns
- Rewarded flows: Offer a second scratch card after watching a rewarded ad. Validate ad completion before awarding the scratch.
- F2P retention: Daily scratch card streaks increase return rates. Use server to increment streaks and control rare prizes.
- In-app purchases: Allow users to purchase premium brush types, second attempts, or guaranteed prizes. Ensure IAP flows call your backend to consume purchases and mark rewards as delivered.
- Limited-time events: Provide seasonal cards with themed visuals and limited prize pools. Use remote config to change content without shipping updates.
Testing and QA
- Test on all target devices and OS versions. Mask rendering and touch/finger smoothing behave differently across GPUs.
- Use debug modes provided by the SDK to reveal internal state, seed values, and mask alpha maps.
- Simulate low-memory conditions and background/foreground transitions to ensure mask state persistence.
- For multiplayer or social sharing, test snapshot capture and upload of revealed content.
Troubleshooting (common issues)
- No reveal visible: Check mask alpha channel and the scratch brush settings. Verify the mask texture is imported with Read/Write enabled if the SDK requires CPU access.
- Events not firing: Ensure you’ve subscribed to the SDK events on the main thread. In Unreal, ensure the plugin is initialized before UI is created.
- Build errors on iOS/Android: Confirm native libraries are present and the correct architectures are selected. For Android ensure Gradle manifest merging didn’t strip required permissions.
- Performance hitches: Lower mask size, reduce brush smoothing, or enable GPU mode.
Recommended workflow
1. Integrate SDK and initialize in a minimal test scene.
2. Implement simple scratch flow and wire up OnScratchComplete to a mock server for prize validation.
3. Iterate on visuals, brush feel, and performance profiling.
4. Add analytics and monetization hooks.
5. Harden server-side validation and improve security (tokenization, rate limits).
6. QA across devices, then roll out in staged releases and monitor analytics.
Conclusion
ScratchCard Pro can add a tactile, rewarding mechanic to games when integrated thoughtfully. Follow platform-specific steps for Unity and Unreal, prioritize server-side validation for rewards, and optimize mask sizes and brush behavior for performance. With careful analytics and UX tuning, scratch cards can drive engagement and monetization without harming user experience. If your SDK provider offers sample projects, use them as a reference to accelerate integration.
