Enhanced OfferWall SDK Guide

This documentation describes additional features of the OfferWall SDK that will help improve user interaction with your application.

Checking for Available Offers

The hasOffers() function allows you to determine if any offers are available to the user before displaying the OfferWall button.

// After SDK initialization
const sdk = await loadOfferWallSDK({
  projectId: 'YOUR_PROJECT_ID'
});

// Check if there are available offers
if (sdk.hasOffers()) {
  // Show the OfferWall button
  document.getElementById('offerwall-button').style.display = 'block';
} else {
  // Hide the button or show alternative content
  document.getElementById('offerwall-button').style.display = 'none';
  document.getElementById('no-offers-message').style.display = 'block';
}

This allows you to:

• Improve user experience by not showing an empty OfferWall
• Optimize the interface by hiding irrelevant elements
• Offer alternative content when offers are unavailable

Processing Pending Rewards

The pending() method allows you to retrieve and process rewards that are waiting for confirmation. This is particularly useful for recovering from interrupted sessions.

// Check for rewards awaiting confirmation
async function checkPendingRewards() {
  const pendingRewards = await sdk.pending();
  console.log(`Found ${pendingRewards.length} pending rewards`);
  
  // Process each reward
  for (const reward of pendingRewards) {
    // Your code to verify the reward
    await processReward(reward);
  }
}

async function processReward(reward) {
  // Send to your server for verification
  const confirmationHash = await validateRewardOnServer(reward);
  
  // Confirm the reward in the SDK
  await sdk.confirmReward(reward.rewardId, confirmationHash);
}

Reward Structure

{
  rewardId: "123",         // Reward ID
  userId: "user_456",      // User ID
  projectId: "YOUR_PROJECT_ID",        // Project ID
  hash: "verification_hash", // Verification hash
  amount: 500,             // Amount of points/currency
  description: "For completing the task" // Reward description
}

Recommendations for Server-side Validation

When implementing reward validation on your server, it's recommended to:

1. Idempotence - your server should correctly handle repeated attempts to confirm the same reward:

// Example pseudocode for server-side
function validateReward(rewardId, hash, userId) {
  // Verify hash validity
  if (!isValidHash(rewardId, hash, userId)) {
    return { success: false, error: 'Invalid hash' };
  }
  
  // Check if the reward has already been claimed
  if (isRewardAlreadyClaimed(rewardId, userId)) {
    // Return success but don't issue the reward again
    return { 
      success: true, 
      confirmationHash: getStoredConfirmationHash(rewardId),
      alreadyClaimed: true 
    };
  }
  
  // Issue the reward to the user
  grantRewardToUser(userId, rewardId);
  const confirmationHash = generateConfirmationHash(rewardId);
  storeConfirmationHash(rewardId, confirmationHash);
  
  return { 
    success: true,
    confirmationHash: confirmationHash
  };
}

2. Status Tracking - always store information about reward status to avoid duplication

Event Subscription System

The SDK provides an event system that allows you to react to various events in the OfferWall lifecycle.

Key Events

// Subscribe to SDK initialization
sdk.on('initialized', (data) => {
  console.log('SDK initialized:', data.userId, data.projectId);
  // Enable UI elements dependent on initialization
});

// Subscribe to OfferWall loading
sdk.on('loaded', () => {
  console.log('OfferWall loaded');
  // Hide the loading indicator
  hideLoadingIndicator();
});

// Subscribe to OfferWall opening
sdk.on('opened', () => {
  console.log('OfferWall opened');
  // Track analytics event
  analytics.track('offerwall_opened');
});

// Subscribe to OfferWall closing
sdk.on('closed', () => {
  console.log('OfferWall closed');
  // Update data after closing
  refreshUserBalance();
});

Unsubscribing from Events

// Define handler function
const handleOpened = () => {
  console.log('OfferWall opened');
};

// Subscribe to event
sdk.on('opened', handleOpened);

// Later unsubscribe from event
sdk.off('opened', handleOpened);

// Unsubscribe from all events
sdk.offAll();

Complete Integration Example

import { loadOfferWallSDK } from 'offerwall-sdk-loader';

// Initialize SDK
async function initSDK() {
  try {
    const sdk = await loadOfferWallSDK({
      projectId: 'your-project-id',
      apiUrl: 'https://api.example.com'
    });
    
    // Set up event handlers
    sdk.on('initialized', (data) => {
      console.log('SDK initialized for user', data.userId);
    });
    
    sdk.on('loaded', () => {
      console.log('OfferWall loaded');
      hideLoadingIndicator();
    });
    
    sdk.on('opened', () => {
      console.log('OfferWall opened');
      trackEvent('offerwall_opened');
    });
    
    sdk.on('closed', () => {
      console.log('OfferWall closed');
      refreshUserData();
    });
    
    // Check for pending rewards
    await checkPendingRewards(sdk);
    
    // Update UI based on offer availability
    updateOfferWallButton(sdk);
    
    // Attach handlers to buttons
    document.getElementById('offerwall-button').addEventListener('click', () => {
      sdk.open();
    });
    
    return sdk;
  } catch (error) {
    console.error('Error initializing SDK:', error);
    showErrorMessage('Failed to load offers. Please try again later.');
  }
}

// Check for pending rewards
async function checkPendingRewards(sdk) {
  const pendingRewards = await sdk.pending();
  console.log(`Found ${pendingRewards.length} pending rewards`);
  
  if (pendingRewards.length > 0) {
    showNotification(`You have ${pendingRewards.length} unclaimed rewards!`);
    
    for (const reward of pendingRewards) {
      try {
        const confirmationHash = await validateRewardOnServer(reward);
        await sdk.confirmReward(reward.rewardId, confirmationHash);
      } catch (error) {
        console.error('Error confirming reward:', error);
      }
    }
    
    refreshUserBalance();
  }
}

// Update OfferWall button
function updateOfferWallButton(sdk) {
  const button = document.getElementById('offerwall-button');
  
  if (sdk.hasOffers()) {
    button.style.display = 'block';
    button.disabled = false;
  } else {
    button.style.display = 'none';
    document.getElementById('no-offers-message').style.display = 'block';
  }
}

// Initialize SDK when the page loads
document.addEventListener('DOMContentLoaded', initSDK);

By using these additional features, you can create a more integrated and responsive OfferWall experience for your users. The event system provides real-time updates, while the pending rewards functionality ensures that users always receive their earned rewards, even if interruptions occur.