LogoLogo
SDK ReferenceChangelogBlogStatusGet HelpGo To Dashboard
  • Introduction
  • Basics
    • How ContextDecision Works
    • How ContextPush Works
    • Getting Started
  • Context Decision
    • Logging Conversions
    • Revenue Outcomes
      • Logging Revenue with RevenueCat
    • Adding Entry Points
    • Release Checklist
    • Advanced
      • Custom Signals
      • Alternative Outcomes
      • Custom Outcome Metadata
      • Listening for Good Moments
      • Model Distribution Methods
      • Custom A/B Test Segmentation
      • Analytics & Reporting
  • Context Push
    • Integrating ContextPush
    • Push Notification Providers
      • OneSignal
      • Customer.io
      • Simple Web Request
    • Release Checklist
    • Analytics & Reporting
  • Discover By Use Cases
    • Multivariate Monetization
    • Inline Banners
  • Other Information
    • Glossary
    • Updating Your SDK
    • Minimum SDK Requirements
    • FAQ
    • Get Help
    • Changelog
  • Advanced
    • Custom Configuration
    • Capturing Context In Key Moments
Powered by GitBook
On this page
  • Generic Web Request
  • API Token
  • Endpoint to send messages
  • Endpoint to cancel delivery of a message

Was this helpful?

  1. Context Push
  2. Push Notification Providers

Simple Web Request

Learn how to integrate ContextPush using simple web requests.

Generic Web Request

API Token

To obtain your API token, please provide us with your push certificate. You can either create a new push certificate for us or use your existing one.

Endpoint to send messages

POST https://push.contextsdk.com/v1/campaigns/schedule_message_for_user

This endpoint is used to schedule a push notification message for a specific user on the ContextSDK platform. You need to send one web request per message you want to send.

Headers

Header
Description
Example Value

Authorization

The token used to authorize the request. Replace with a valid authentication token. Reach out to us to get access

Token CTX-1234567890abcdef

Request Body

Parameter
Type
Description
Example Value

bundle_id

String

The unique identifier of the application bundle

com.contextsdk.demo

platform

String

The platform on which the user will receive the message

ios

user_id

String

The unique identifier of the user

user@contextsdk.com

deliver_within_hours

Int

The time frame, in hours, within which the message should be delivered

6

campaign_id

String

The same type of message should always have the same campaign_id. This is used for performance insights, and to train custom models for each campaign_id.

daily-reminder

idempotency_key

String (optional)

A unique identifier for the push notification message. If the same idempotency_key is used in multiple requests, only the last request will be processed.

1234567890abcdef

delivery_method

String (optional)

The delivery method for the message. Possible values are context_aware and traditional. If no value is specified, we will automatically do an AB test on your behalf. If you already have the AB test cohort for the user, you can specify the corresponding value here.

context_aware

content

Object

Details of the message to be delivered. See subfields below.

title

String

The title of the push notification message.

James, It's time to learn English

subtitle

String (optional)

The subtitle of the push notification message

Start your English course now!

body

String

The body content of the push notification message

It's time to learn English. Start your course now!

sound

String (optional)

The full name of the audio file in the root of the main app bundle

sosumi.caf

badge

Int (optional)

The number to display as the badge of the app icon, 0 resets the badge

1

userInfo

Object (optional)

Custom data to be sent with the push notification message

{ "key": "value" }

thread-id

String (optional)

An app-specific identifier for grouping related notifications. This value corresponds to the threadIdentifier property in the UNNotificationContent object.

imageUrl

String (optional)

A URL pointing to a image file hosted publicly on the internet. Requires setting up a notification service extension to fetch the image, see section below

Example Request

POST /v1/campaigns/schedule_message_for_user HTTP/1.1
Host: push.contextsdk.com
Authorization: Token CTX-123456789ABCD
Content-Type: application/json

{
    "bundle_id": "com.contextsdk.demo",
    "platform": "ios",
    "user_id": "user@contextsdk.com",
    "content": {
        "title": "James, it's time for your english course!",
        "body": "Start your english course now!"
    },
    "deliver_within_hours": 3,
    "campaign_id": "daily-reminder",
    "delivery_method": "context_aware"
}

Alternative delivery window specification

The above deliver_within_hours parameter specifies the time frame within which the message should be delivered from the current time onwards. If you want to specify a specific time frame within which the message should be delivered, you can use the target_delivery_time parameter instead. That parameter should be a string in the format ISO 8601, e.g. 2025-01-25T18:32:00Z.

Localization

ContextPush has native support to localize messages for your users. The content.title, content.body, and content.subtitle fields support supplying a dictionary of translations instead of just a single string. ContextPush will then use the localization matching the locale the receiving user has set on their phone. A content.default_locale needs to be specified to determine which translation to use if none matches the users locale.

All translated fields need to specify all locales, meaning it's not supported to translate title and body in two different sets of languages.

Example Request

POST /v1/campaigns/schedule_message_for_user HTTP/1.1
Host: push.contextsdk.com
Authorization: Token CTX-123456789ABCD
Content-Type: application/json

{
    "bundle_id": "com.contextsdk.demo",
    "platform": "ios",
    "user_id": "user@contextsdk.com",
    "content": {
        "default_locale": "en",
        "title": {
          "en": "James, it's time for your english course!",
          "de": "James, es ist Zeit für deinen Englischkurs!"
        },
        "body": {
          "en": "Start your english course now!",
          "de": "Beginne jetzt mit deinem Englischkurs!"
        }
    },
    "deliver_within_hours": 3,
    "campaign_id": "daily-reminder",
    "delivery_method": "context_aware"
}

Supporting images

For context aware push notifications ContextSDK will handle fetching and setting the image on the notification before display. For notifications that are delivered traditionally (such as when explicitly using the traditional delivery mode, or in case there was no good moment during the delivery window) a UNNotificationServiceExtension needs to be used.

In your UNNotificationServiceExtension you can fetch the image and set it on the notification. Below is a full example for downloading and setting the image which can be integrated with your existing UNNotificationServiceExtension:

import UserNotifications

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {

        self.contentHandler = contentHandler
        guard let bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent) else {
            contentHandler(request.content)
            return
        }
        self.bestAttemptContent = bestAttemptContent

        if let imageUrl = bestAttemptContent.userInfo["ctx_image_url"] as? String,
           let idempotencyKey = bestAttemptContent.userInfo["ctx_idempotency_key"] as? String,
            let fileUrl = URL(string: imageUrl) {
            let task = URLSession.shared.downloadTask(with: URLRequest(url: fileUrl)) { url, response, error in
                if let httpResponse = response as? HTTPURLResponse, (200...299).contains(httpResponse.statusCode) {
                    if let url = url,
                       let attachment = UNNotificationAttachment.saveImageToDisk(fileIdentifier: "\(idempotencyKey).jpg", sourcePath: url , options: nil) {
                        bestAttemptContent.attachments = [ attachment ]
                    }
                }
                contentHandler(bestAttemptContent)
            }
            task.resume()
        } else {
            contentHandler(request.content)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        if let contentHandler = contentHandler, let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}

@available(iOSApplicationExtension 10.0, *)
extension UNNotificationAttachment {

    static func saveImageToDisk(fileIdentifier: String, sourcePath: URL, options: [NSObject : AnyObject]?) -> UNNotificationAttachment? {
        let fileManager = FileManager.default
        let folderName = ProcessInfo.processInfo.globallyUniqueString
        guard let folderURL = NSURL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(folderName, isDirectory: true) else {
            return nil
        }

        do {
            try fileManager.createDirectory(at: folderURL, withIntermediateDirectories: true, attributes: nil)
            let fileURL = folderURL.appendingPathComponent(fileIdentifier)
            try fileManager.moveItem(at: sourcePath, to: fileURL)
            let attachment = try UNNotificationAttachment(identifier: fileIdentifier, url: fileURL, options: options)
            return attachment
        } catch let error {
            print(error)
        }

        return nil
    }
}

Note on traditional delivery

When using the traditional delivery method, the notification will be sent to the user as soon as possible, usually with in at most 5 minutes. As such cancelling is only possible immediately after scheduling it.

Endpoint to cancel delivery of a message

POST https://push.contextsdk.com/v1/campaigns/cancel_message_for_user

If a message is no longer applicable delivery can be cancelled if the message was not shown to the user yet. This requires you to set an idempotency key when scheduling the message. Cancelling a message is not possible if relying on the auto generated idempotency key.

Headers

Header
Description
Example Value

Authorization

The token used to authorize the request. Replace with a valid authentication token. Reach out to us to get access

Token CTX-1234567890abcdef

Request Body

Parameter
Type
Description
Example Value

bundle_id

String

The unique identifier of the application bundle

com.contextsdk.demo

platform

String

The platform on which the user will receive the message

ios

user_id

String

The unique identifier of the user

user@contextsdk.com

campaign_id

String

The same type of message should always have the same campaign_id. This is used for performance insights, and to train custom models for each campaign_id.

daily-reminder

idempotency_key

String

A unique identifier for the push notification message. If the same idempotency_key is used in multiple requests, only the last request will be processed.

1234567890abcdef

Example Request

POST /v1/campaigns/cancel_message_for_user HTTP/1.1
Host: push.contextsdk.com
Authorization: Token CTX-123456789ABCD
Content-Type: application/json

{
    "bundle_id": "com.contextsdk.demo",
    "platform": "ios",
    "user_id": "user@contextsdk.com",
    "campaign_id": "daily-reminder",
    "idempotency_key": "427c60db-c3df-4098-a0f7-9b5d153438f4"
}
PreviousCustomer.ioNextRelease Checklist

Last updated 1 month ago

Was this helpful?