Overview
The Lula Direct SDK provides everything you need to embed a branded shopping experience directly into your mobile or web applications. Built for React Native, iOS (Swift), and Android (Kotlin), the SDK offers complete control over your digital storefront while leveraging Lula’s powerful commerce platform.The SDK handles authentication, deep linking, order processing, and native payment integration automatically - allowing you to launch a branded ordering experience in under a week.
When to Use Lula Direct SDK
Mobile App Integration
Native mobile experiences
- Embed storefront in React Native apps
- Native iOS (Swift) integration
- Native Android (Kotlin) integration
- Seamless in-app shopping
Rapid Development
Pre-built components
- Complete WebView-based storefront
- Automatic JWT authentication
- Ready-to-use order flows
- Launch in under a week
Branded Experience
White-label control
- Your app, your brand
- Custom WebView configuration
- Deep linking to products
- Native payment integration
Simplified Integration
Minimal code required
- Single component implementation
- Handles authentication automatically
- Built-in order management
- Real-time inventory sync
Getting Started
Follow these steps to integrate Lula Direct SDK into your application:1
Install Dependencies
Add the SDK and required packages
For native iOS/Android integration, you’ll also need:
- iOS: JWTKit library
- Android: Auth0 JWT library
2
Configure Credentials
Provide your application credentialsRequired:
secretKey
- JWT signing key (≥32 characters)appBundleId
- Your app’s bundle identifiermemberId
- Your Lula member ID
Store your secret key securely. Never commit it to version control.
3
Initialize SDK
Configure the SDK when your app starts
Store secret keys securely using environment variables
4
Embed Storefront
Add LulaDirectView component to your app
5
Test & Deploy
Validate your integration
- Test order flows end-to-end
- Verify payment methods (Apple Pay/Google Pay)
- Test deep linking to products/categories
- Validate error handling
- Deploy to production
Use development environment for testing before production deployment
Core Concepts
How It Works
The Lula Direct SDK uses a WebView-based approach to embed the Lula storefront into your native application. Here’s how the key components work together:1
JWT Authentication
The SDK generates secure JWT tokens using your
secretKey
and appBundleId
. These tokens authenticate API requests and contain customer information for personalized experiences.2
WebView Integration
LulaDirectView
renders the Lula storefront in a React Native WebView with automatic authentication, deep linking support, and bi-directional message passing.3
Token Caching
JWT tokens are cached in AsyncStorage for 24 hours (configurable) to minimize regeneration and improve performance. When a cached token expires, the SDK automatically generates a new token and caches it.
4
Event Communication
The WebView sends events (order completion, missing data) to your app via
postMessage
, triggering your callback functions.Key Features
WebView Integration
Seamless embedding
- React Native WebView component
- Automatic authentication
- Deep linking support
- Native payment methods
JWT Authentication
Secure token-based auth
- Automatic token generation
- Token caching with expiration
- HS256 signing algorithm
- 24-hour default expiry
Order Management
Complete order handling
- Order completion callbacks
- Real-time status updates
- Cart modification support
- Order history access
Native Payments
Platform-specific payments
- Apple Pay (iOS)
- Google Pay (Android)
- Secure payment processing
- PCI compliance built-in
API Reference
Component Props
LulaDirectView
The main React Native component for embedding the Lula Direct storefront. It handles WebView initialization, JWT authentication, URL construction, and message passing between the native app and the web storefront.
Prop | Type | Required | Default | Description |
---|---|---|---|---|
memberId | string | Yes | - | Your Lula member ID for authentication. Used in URL construction and JWT payload. |
storeId | string | No | - | Specific store ID to display. If omitted, the storefront may show all stores for the member or a default store. |
hideNav | boolean | No | true | Controls visibility of the Lula navigation bar in the embedded storefront. |
customerInfo | object | No | {} | Customer details used for JWT authentication and pre-filling checkout information. See CustomerInfo interface below. |
deepLinkPath | string | No | - | Path to navigate to within the storefront (e.g., /product/123 , /category/beer ). Encoded as both a JWT claim and URL parameter. |
onOrderComplete | function | No | - | Callback fired when an order is successfully completed. Receives order data parsed from WebView message with type ORDER_COMPLETE . |
onMissingData | function | No | - | Callback fired when the storefront requires additional customer information. Receives field names from WebView message with type MISSING_DATA . |
enableApplePay | boolean | No | false | Enables Apple Pay support on iOS. Sets allowsBackForwardNavigationGestures to true. |
enableGooglePay | boolean | No | false | Enables Google Pay support on Android. Reserved for future Google Pay-specific WebView settings. |
sdkConfig | object | No | - | Partial SDK configuration to override global settings for this instance. See LulaSDKConfig below. |
storeUrl | string | No | - | Deprecated. Base URL override for the Lula service. Use sdkConfig.baseUrl instead. |
CustomerInfo
Interface
Customer information object passed to LulaDirectView
. All fields are optional and used to pre-populate the storefront and generate the JWT token.
CustomerInfo Properties
CustomerInfo Properties
Customer’s full name. Included in JWT payload as
member.name
for pre-filling checkout forms.Customer’s email address. Included in JWT payload as
member.email
for account identification and order confirmations.Customer’s phone number. Included in JWT payload as
member.phone
for delivery updates and customer service.Customer’s address object. Included in JWT payload as
member.address
for delivery and billing purposes.Age verification flag indicating if customer is 21 years or older. Required for purchasing restricted products like alcohol. Included in JWT payload as
member.age21
.Setting this to false or omitting it may prevent purchase of age-restricted items
WebView Message Events
The component listens for messages from the WebView and triggers callbacks based on the message type:Message Event Types
Message Event Types
Fired when: An order is successfully completed in the storefrontCallback:
onOrderComplete(order)
Payload: Order object containing order details (structure determined by Lula backend)Fired when: The storefront requires additional customer informationCallback:
onMissingData(fields)
Payload: Array or object containing field names that need to be providedSDK Configuration
initLulaSDK(config, isProd?)
Initialize the SDK with configuration options. This should be called once when your application starts, before using LulaDirectView
.
Parameters:
config
(Partial<LulaSDKConfig>) - Configuration object with properties to overrideisProd
(boolean, optional) - Iftrue
, uses production defaults; otherwise uses development defaults
LulaSDKConfig
object with merged configuration
LulaSDKConfig Properties
LulaSDKConfig Properties
Base URL for the Lula Direct service. All storefront URLs are constructed by appending paths to this base.Default Values:
- Development:
https://dev.lulacommerce.com
- Production:
https://client.lulacommerce.com
Can be overridden for local development (e.g.,
http://localhost:8000
)Secret key used for JWT signing with HS256 algorithm. Must be at least 32 characters long.Security Requirements:
- Store securely using environment variables
- Never hardcode in client-side code for production
- Consider backend JWT generation for sensitive applications
- Development:
dev-secret-key-at-least-32-characters-long
- Production: Must be provided (no default)
Production apps must provide a secure secret key
Your application’s bundle identifier (iOS) or package name (Android). Used as the JWT
iss
(issuer) claim.Examples:- iOS:
com.yourcompany.yourapp
- Android:
com.yourcompany.yourapp
- Development:
com.yourapp.dev
- Production: Must be provided (no default)
JWT token expiration time in minutes. Tokens are cached and reused until expiration.Default:
1440
(24 hours)Considerations:- Longer expiry = fewer token regenerations but potential security concerns
- Shorter expiry = more frequent regenerations but better security
- Cached tokens are automatically cleared on user logout via
clearLulaJWTCache()
Default deep link path used when no
deepLinkPath
is specified in generateLulaJWT()
.Default: /store/default
Examples:/store/123
/category/featured
/product/new-arrivals
Utility Functions
generateLulaJWT(config)
Generates a JWT token for Lula Direct authentication using the HS256 algorithm. The token is automatically cached in AsyncStorage and reused until expiration.
Parameters: LulaJWTConfig
object
Returns: Promise<string>
- The JWT token
Behavior:
- Checks AsyncStorage for a valid cached token
- If cached token exists and hasn’t expired, returns it immediately
- Otherwise, generates a new token with the current timestamp
- Caches the new token with its expiration timestamp
- Returns the token
LulaJWTConfig Parameters
LulaJWTConfig Parameters
Member ID for authentication. If not provided, defaults to
"user123"
(not recommended for production).User’s display name. Included in JWT
member.name
claim.User’s email address. Included in JWT
member.email
claim.User’s phone number. Included in JWT
member.phone
claim.User’s address object. Included in JWT
member.address
claim. Structure is flexible.Age verification flag. Included in JWT
member.age21
claim.Whether to hide navigation in the storefront. Included in JWT
hideNav
claim.Path to navigate to. Included in JWT
path
claim. Falls back to sdkConfig.defaultPath
if not provided.getLulaUrl(path)
Constructs a full URL by combining the configured baseUrl
with the provided path. Automatically handles path formatting.
Parameters:
path
(string) - Relative path (e.g.,/product/123
)
string
- Complete URL
Behavior:
- Ensures path starts with
/
- Handles company-specific subdomains (
.lulacommerce.com
) - Works with custom development URLs
clearLulaJWTCache()
Clears the cached JWT token and its expiration timestamp from AsyncStorage. Should be called when the user logs out or switches accounts to ensure a fresh token is generated on next login.
Parameters: None
Returns: Promise<void>
Storage Keys Cleared:
lula_jwt_token
- The cached JWT token stringlula_jwt_expiry
- The token expiration timestamp
Advanced Usage
Manual URL Generation
For custom WebView setups or external browser opening:The JWT token is appended as a
token
query parameter for authentication.Native Platform Integration
iOS (Swift) Implementation
Configuration
JWT Generation
WebView Integration
Android (Kotlin) Implementation
Configuration
JWT Generation
WebView Integration
Security Considerations
Important Security Guidelines
Secret Key Management
- Never hardcode production keys in client-side code
- Use environment variables for configuration
- Consider backend JWT generation for production apps
- Use secure storage:
- iOS: Keychain
- Android: EncryptedSharedPreferences
- React Native: react-native-encrypted-storage
WebView Security
JWT Best Practices
- Monitor token expiration (default: 24 hours)
- Clear tokens on user logout
- Implement token refresh mechanisms
- Validate token structure and claims
Troubleshooting
Common Issues
WebView not rendering / Blank Screen
WebView not rendering / Blank Screen
Possible causes and solutions:
- Verify
react-native-webview
is correctly installed and linked - Check
baseUrl
ininitLulaSDK
is correct and reachable - Ensure
memberId
is provided ininitLulaSDK
orLulaDirectView
- Check console for errors during initialization or JWT generation
Authentication Errors / Invalid Token
Authentication Errors / Invalid Token
Token validation issues:
- Verify
secretKey
matches your Lula Direct account - Ensure
appBundleId
is correctly configured - Confirm
secretKey
is at least 32 characters long - Check JWT expiration (default: 24 hours)
- Call
clearLulaJWTCache()
to refresh token
Deep Linking Not Working
Deep Linking Not Working
Navigation problems:
- Ensure
deepLinkPath
is a valid Lula Direct path:/store/STORE_ID
/product/PRODUCT_ID
/category/CATEGORY_ID
- Verify JWT generation includes the
deepLinkPath
- Check path format matches Lula’s routing structure
Missing Data Prompts
Missing Data Prompts
Insufficient customer information:
- Provide complete
customerInfo
inLulaDirectView
- Include required fields:
name
,email
,phone
- Add
age21
verification for restricted products - Check
onMissingData
callback for specific requirements
Native Payment Methods Not Working
Native Payment Methods Not Working
Apple Pay / Google Pay issues:
- Verify
enableApplePay
is set on iOS devices - Verify
enableGooglePay
is set on Android devices - Check device supports the payment method
- Ensure payment credentials are configured in Lula
Native Integration Issues
iOS Troubleshooting
iOS Troubleshooting
WebView not loading:
- Verify generated URL is correct
- Check network connectivity and SSL certificates
- Enable required WebView settings
- Review WKWebView console logs
- Verify JWTKit library is installed
- Check secret key length (≥32 characters)
- Ensure proper date handling for expiration
- Validate payload structure
Android Troubleshooting
Android Troubleshooting
WebView not loading:
- Enable JavaScript and DOM storage
- Check network permissions in manifest
- Verify URL format and accessibility
- Review WebView client logs
- Verify Auth0 JWT library dependency
- Check algorithm configuration (HS256)
- Ensure proper time calculation
- Validate claim structure
Additional Resources
API Documentation
REST API reference for custom integrations
Integration Guide
Platform integrations and capabilities
Platform Setup
Complete getting started guide
Support
Need help? Contact your Lula representative for:
- SDK access and credentials
- Technical implementation support
- Production deployment coordination
- Troubleshooting assistance