Push Notifications

Notifications are a powerful way to build stronger relationships with your customers by keeping them engaged with your service. Gameball provides default notification options and supports custom notification systems through webhooks.

Notification Options

Gameball offers multiple ways to deliver notifications to your customers:

In-App Notifications

Web ApplicationsBuilt-in notifications for web applications that display within your app interface.

Mobile AppsPush notifications using Firebase for iOS and Android mobile applications.

Custom Systems

WebhooksBuild your own notification system using SMS, WhatsApp, Amazon SNS, Twilio, or other third-party services via webhooks.

Customer Notifications API

Programmatic AccessRetrieve and display notifications programmatically using the Customer Notifications API.

Mobile Push Notifications (Firebase)

Gameball uses Firebase to deliver push notifications for mobile applications. This includes support for iOS and Android apps.

Prerequisites: Before implementing push notifications, you must configure your Firebase account in your Gameball dashboard. Follow the steps in the Gameball Help Center article on configuring Firebase.

How It Works

Configure Firebase

Set up Firebase Cloud Messaging (FCM) and configure it in your Gameball dashboard.

This configuration links your Firebase project with Gameball so notifications can be delivered through Firebase.

Device tokens are unique identifiers for each mobile device. You need to register them so Gameball knows where to send push notifications.

Handle Notifications

Configure your app to handle incoming push notifications and display them appropriately.

Platform-Specific Guides

iOS
Android
React Native

For iOS apps, integrate push notifications by:

Configure AppDelegate

Inherit required protocols in your AppDelegate class:

class AppDelegate: UIResponder, UIApplicationDelegate, 
                  UNUserNotificationCenterDelegate, MessagingDelegate {
  var gameballApp: Gameball?
}

Initialize Firebase

Add Firebase configuration in didFinishLaunchingWithOptions():

FirebaseApp.configure()
registerForPushNotifications()

Request Permissions

Request notification permissions from the user:

func registerForPushNotifications() {
  UNUserNotificationCenter.current()
    .requestAuthorization(options: [.alert, .sound, .badge]) {
      [weak self] granted, error in
      UNUserNotificationCenter.current().delegate = self
      Messaging.messaging().delegate = self
      guard granted else { return }
      self?.getNotificationSettings()
    }
}

Register the device token with Gameball using gameballApp.registerDevice. Refer to the Firebase documentation for accessing the registration token.

See the iOS Push Notifications installation guide for complete implementation details.

Custom Notification Systems via Webhooks

If you have your own notification system—like SMS messaging, WhatsApp bots, or third-party services like Amazon SNS or Twilio—Gameball makes this easy by using webhooks to notify your system whenever a notification needs to be sent.

How Webhooks Work

Build Webhook Endpoint

Create a webhook endpoint on your server (written in any language like Ruby, PHP, or Node.js) that processes incoming requests.

This endpoint will receive POST requests from Gameball containing notification data.

Provide Endpoint URL

Share your endpoint URL (e.g., https://yourdomain.com/webhook-endpoint) with Gameball through your dashboard.

Receive Notifications

Gameball sends a POST request with all necessary notification data to your endpoint whenever a customer should receive a notification.

Process and Deliver

Use the notification data to send messages through your preferred channels (SMS, WhatsApp, push, etc.).

Implementation Steps

Step 1: Build a Notifications Endpoint

Create a webhook endpoint on your server:

app.post('/gb-webhook/notification', (request, response) => {
  // Process notification here
});

This endpoint will be invoked whenever Gameball needs to send a notification to your customer.

Step 2: Activate Notifications Webhook

In your Gameball dashboard:

Navigate to Settings

Go to Admin Settings > Account Integration > Webhooks.

Add Endpoint URL

Add your notification endpoint URL (e.g., www.yourdomain.com/gb-webhook/notification) to the Notification Webhook field.

Update Webhook

Click Update Webhook to save your configuration.

Step 3: Verify Webhook Signatures

Security Critical: Always verify that incoming requests are legitimate requests from Gameball and not malicious attempts to spam your system.

Verify webhook signatures using the SHA1 hash in the X-GB-Signature header:

const crypto = require("crypto");

function verifySignature(request) {
  const SECRET_KEY = process.env.SECRET_KEY;
  // Get the signature from the header
  const signature = request.headers["x-gb-signature"];
  if (!signature) return false;

  // Compute the signature using the payload and secret key
  const payload = JSON.stringify(request.body);
  const computedSignature = crypto
    .createHash("sha1")
    .update(payload + ":" + SECRET_KEY)
    .digest("hex");

  // Compare the signatures
  return computedSignature === signature;
}

app.post('/gb-webhook/notification', (request, response) => {
  // verify the request
  if (verifySignature(request) == false) {
    return response.status(401).send('Unauthorized');
  }
  
  // Process notification
});

For more information on webhook verification, see the Webhooks documentation.

Step 4: Process Notification Data

The webhook request contains all the data needed to send notifications to your customers. Here’s an example of the notification payload:

{
  "event": "customer.notification.push",
  "client_id": "2155",
  "customer_id": "webhook-test",
  "gb_customer_id": 1234,
  "created_at": "2024-11-12T19:02:24.631Z",
  "data": [
    {
      "local": "en",
      "icon": "https://example.com/image.webp",
      "body": "Your recent activities have been amazing! Keep up the great work and enjoy your rewards!",
      "title": "Well Done!"
    }
  ]
}

Webhook Fields

The notification webhook includes:

event: Identifies this as a customer notification push event
client_id: Your app’s unique identifier
customer_id: The customer identifier you use in your system
gb_customer_id: Gameball’s internal customer identifier
created_at: Timestamp when the notification was created
data: Array of notification content in different languages (title, body, icon, local)

Implementation Examples

SMS Integration
WhatsApp Integration
Push Notifications (AWS SNS)
Multiple Channels

Send notifications via SMS using your SMS gateway:

app.post('/gb-webhook/notification', (request, response) => {
  if (verifySignature(request) == false) return;
  
  let webhookData = request.body;
  let customerId = webhookData.customer_id;
  let customerInfo = getCustomerDetails(customerId);
  
  // Send SMS to customer's phone number
  SMSGateway.sendMessage({
    phoneNumber: customerInfo.phone,
    messageTitle: webhookData.data[0].title,
    messageContent: webhookData.data[0].body
  });
});

Send notifications via WhatsApp using WhatsApp Business API or Twilio:

app.post('/gb-webhook/notification', (request, response) => {
  if (verifySignature(request) == false) return;
  
  let webhookData = request.body;
  let customerId = webhookData.customer_id;
  let customerInfo = getCustomerDetails(customerId);
  
  // Send WhatsApp message
  WhatsappHandler.sendWhatsappMessage({
    phoneNumber: customerInfo.phone,
    messageContent: webhookData.data[0].body
  });
});

Send push notifications using AWS SNS:

app.post('/gb-webhook/notification', (request, response) => {
  if (verifySignature(request) == false) return;
  
  let webhookData = request.body;
  let customerId = webhookData.customer_id;
  let customerInfo = getCustomerDetails(customerId);
  
  // Send push notification using device token
  SNS.sendNotification({
    token: customerInfo.deviceToken,
    title: webhookData.data[0].title,
    body: webhookData.data[0].body
  });
});

AWS SNS uses device tokens to identify mobile devices. Store each customer’s device token in your database.

You can send notifications through multiple channels simultaneously:

app.post('/gb-webhook/notification', (request, response) => {
  if (verifySignature(request) == false) return;
  
  let webhookData = request.body;
  let customerId = webhookData.customer_id;
  let customerInfo = getCustomerDetails(customerId);
  
  // Send SMS
  SMSGateway.sendMessage({
    phoneNumber: customerInfo.phone,
    messageContent: webhookData.data[0].body
  });
  
  // Send WhatsApp
  WhatsappHandler.sendWhatsappMessage({
    phoneNumber: customerInfo.phone,
    messageContent: webhookData.data[0].body
  });
  
  // Send push notification
  if (customerInfo.deviceToken) {
    SNS.sendNotification({
      token: customerInfo.deviceToken,
      title: webhookData.data[0].title,
      body: webhookData.data[0].body
    });
  }
});

Customer Notifications API

Gameball also provides APIs to retrieve and manage customer notifications programmatically.

Retrieving Notifications

Use the Get Customer Notifications API to fetch a list of notifications for a specific customer:

GET /api/v4.0/integrations/customers/{customerId}/notifications

Response Example:

{
  "notifications": [
    {
      "notificationId": "15227561",
      "title": "Congratulations!",
      "body": "Buy over 500$ and get 10$ 💰 earned. Enjoy your rewards and keep earning more!",
      "isRead": false,
      "createdAt": "2024-11-19T13:39:13.792Z",
      "lang": "en",
      "icon": "https://cdn.gameball.co/uploads/Client_9423/2b2efc2f-b85e-4cce-baf6-380454e4d62ccash.webp"
    }
  ],
  "count": 4,
  "hasMore": false
}

Pagination

Use count and hasMore fields to implement pagination in your UI.

count: Number of notifications in current response
hasMore: Indicates if more notifications are available

Language Support

Request notifications in different languages using the lang query parameter.Example: ?lang=es for Spanish

Marking Notifications as Read

Use the Mark Notifications as Read API to update notification status:

PUT /api/v4.0/integrations/customers/{customerId}/notifications/read
{
  "notificationsIds": [15227561, 15227560]
}

Get Notification Count

Use the Get Customer Notifications Count API to get the total count without fetching all records:

GET /api/v4.0/integrations/customers/{customerId}/notifications/count

Best Practices

Verify Webhooks

Always verify webhook signatures to ensure requests are legitimate and secure.

Handle Errors Gracefully

Implement proper error handling for failed notification deliveries.

Store Device Tokens

For push notifications, securely store device tokens in your database and update them when they refresh.

Respect User Preferences

Allow customers to opt-in or opt-out of different notification types.

Notification Webhooks

Complete webhook documentation for notifications

Customer Notifications API

API reference for retrieving customer notifications

Build Custom UI

Guide on displaying notifications in your custom UI

iOS Push Notifications

iOS-specific push notification integration guide

Getting Started

General

Experiences

More

Push Notifications

Notification Options

In-App Notifications