Custom Signals

Custom signals supplement built-in sensor data, improving decision-making and optimization for your use case.

What are custom signals?

Custom signals allow you to provide additional context when capturing user interactions. ContextSDK processes more than 200 built-in signals, but you can enhance its predictions by including app-specific data — such as in-game progress, friend count, or prior interactions like ad views or feature usage. Any past event that may influence a user’s decision-making process is valuable to include.

Important: Never send personally identifiable information (PII) to the SDK. See Privacy Considerations to learn more.

Why add custom signals?

By adding custom signals, you can:

• Provide additional context when making upsell or engagement decisions to improve the precision of ML models.

• Optimize monetization and user experience based on real-time behavioral data.

Despite that, it's worth noting that adding custom signals is optional. Not all apps and businesses have environment- or user-specific signals that would make a significant difference when deciding whether to show an upsell offer or not.

How to add custom signals

You can define custom signals at two levels:

Global Signals

Global signals apply to all context evaluations and persist across different flows. Use them for app-wide metrics, such as total session count or the number of purchases made. Usage example:

iOS

ContextManager.setGlobalCustomSignal(id: "number_of_levels_completed", value: 21)

Android

Kotlin

ContextSDK.globalCustomSignals["number_of_levels_completed"] = 21

Java

ContextSDK.Companion.getGlobalCustomSignals().set("number_of_levels_completed",
21);

Flutter

_contextSdkPlugin.setGlobalCustomSignals({
  'number_of_levels_completed': 21,
});

Unity

ContextSDKBinding.SetGlobalCustomSignal("number_of_levels_completed", 21);

React Native

setGlobalCustomSignals({ number_of_levels_completed: 21 })

To update a signal, call setGlobalCustomSignal(id:value:) with the same ID and a new value. To remove a global signal, pass a null-like value.

Flow-Specific Signals

Use flow-specific signals when a signal is relevant only to a particular flow. These signals are passed as parameters when capturing a context. Usage example:

iOS

let customSignals: [CustomSignal] = [
    CustomSignalBool(id: "watched_ad", value: true),
    CustomSignalFloat(id: "percentage_onboarding_finished", value: 0.3),
    CustomSignalString(id: "upsell_copy_button_used", value: "Purchase Premium"),
]
ContextManager.fetchContext(flowName: "onboarding_upsell", customSignals: customSignals) { context in
    // Handle context evaluation
}

Android

Kotlin

val customSignals = CustomSignals(
    mapOf(
        "number_of_friends" to SignalValue.IntValue(4),
        "percentage_onboarding_finished" to SignalValue.FloatValue(0.3f),
        "upsell_copy_button_used" to SignalValue.StringValue("Purchase Premium"),
    )
)
ContextSDK.fetchContext("onboarding_upsell", 3, customSignals) { context ->
    // Handle context evaluation
}

Java

CustomSignals customSignals = new CustomSignals();
customSignals.set("number_of_friends", 4);
customSignals.set("percentage_onboarding_finished", 0.3f);
customSignals.set("upsell_copy_button_used", "Purchase Premium");

ContextSDK.Companion.fetchContext("onboarding_upsell", 3, customSignals, realWorldContext -> {
    // Handle context evaluation
});

Flutter

_contextSdkPlugin.fetchContext("onboarding_upsell", customSignals: {
  'watched_ad': true,
  'percentage_onboarding_finished': 0.3,
  'upsell_copy_button_used': 'Purchase Premium',
}, (context) async {
  // Handle context evaluation
})

Unity

CustomSignals customSignals = new CustomSignals();
customSignals.AppendCustomSignal("watched_ad", true);
customSignals.AppendCustomSignal("percentage_onboarding_finished", 0.3f);
customSignals.AppendCustomSignal("upsell_copy_button_used", "Purchase Premium");

ContextSDKBinding.FetchContext("onboarding_upsell", delegate (Context context) {
    // Handle context evaluation
}, customSignals);

React Native

fetchContext({
  flowName: 'onboarding_upsell',
  onContextReady: async (context) => {
    // Handle context evaluation
  },
  customSignals: {
    watched_ad: true,
    percentage_onboarding_finished: 0.3,
    upsell_copy_button_used: 'Purchase Premium',
  },
});

Flow-specific signals ensure that only relevant data is included in decision-making for a particular flow.

Privacy Considerations

When using custom signals, ensure that no personally identifiable information (PII) is included. ContextSDK does not process sensitive data, such as:

• User IDs

• Email addresses or phone numbers

• IP addresses

• Exact locations

• Date of birth or age

• Gender

You are responsible for ensuring that you have the necessary rights to provide data to ContextSDK.

By leveraging custom signals, you can refine ContextSDK’s predictions and optimize monetization strategies — all while maintaining user privacy and security.