crashes in debug mode feedback doc update#35
Conversation
Mintlify-Source: dashboard-editor
Mintlify-Source: dashboard-editor
Mintlify-Source: dashboard-editor
|
|
||
| If you don’t have any attributes, just pass **nil** as the second argument. For eg. | ||
| ## Validations and Restrictions | ||
|
|
There was a problem hiding this comment.
Event attributes have two layers of validation: naming/format rules that always apply, and type validation that crashes the app in Debug builds and silently rejects the attribute in Release builds.
There was a problem hiding this comment.
Why do we want to talk about user attribute in event tracking?
|
|
||
| If you don’t have any attributes, just pass **nil** as the second argument. For eg. | ||
| ## Validations and Restrictions | ||
|
|
There was a problem hiding this comment.
Why do we want to talk about user attribute in event tracking?
|
|
||
| Ensure your events adhere to the following rules to maintain data integrity and prevent rejected payloads: | ||
|
|
||
| - **Consistent Data Types:** Track event attributes without changing their data types. For example, in a purchase event, `amount` and `quantity` should consistently be tracked in numeric form. MoEngage detects the data type automatically unless you explicitly specify it as a String. |
There was a problem hiding this comment.
How is this a validation or restriction? Even if they change the datatype it would get tracked with the new datatype from SDK.
| Ensure your events adhere to the following rules to maintain data integrity and prevent rejected payloads: | ||
|
|
||
| - **Consistent Data Types:** Track event attributes without changing their data types. For example, in a purchase event, `amount` and `quantity` should consistently be tracked in numeric form. MoEngage detects the data type automatically unless you explicitly specify it as a String. | ||
| - **Supported Data Types:** MoEngage supports the following data types: `String`, `Integer`, `Long`, `Double`, `Float`, `Boolean`, `Date`, `GeoLocation`, `JSON Object`, and `JSON Array`. If any other data type is passed, MoEngage SDK rejects the payload. |
There was a problem hiding this comment.
Rejects the specific attribute not the entire thing.
|
|
||
| - **Consistent Data Types:** Track event attributes without changing their data types. For example, in a purchase event, `amount` and `quantity` should consistently be tracked in numeric form. MoEngage detects the data type automatically unless you explicitly specify it as a String. | ||
| - **Supported Data Types:** MoEngage supports the following data types: `String`, `Integer`, `Long`, `Double`, `Float`, `Boolean`, `Date`, `GeoLocation`, `JSON Object`, and `JSON Array`. If any other data type is passed, MoEngage SDK rejects the payload. | ||
| - Starting from SDK version **14.09.00**, passing an unsupported data type in an event property will result in an app crash in debug mode. |
There was a problem hiding this comment.
can be combined with previous point. Does not need another explicit pointer.
| - **Consistent Data Types:** Track event attributes without changing their data types. For example, in a purchase event, `amount` and `quantity` should consistently be tracked in numeric form. MoEngage detects the data type automatically unless you explicitly specify it as a String. | ||
| - **Supported Data Types:** MoEngage supports the following data types: `String`, `Integer`, `Long`, `Double`, `Float`, `Boolean`, `Date`, `GeoLocation`, `JSON Object`, and `JSON Array`. If any other data type is passed, MoEngage SDK rejects the payload. | ||
| - Starting from SDK version **14.09.00**, passing an unsupported data type in an event property will result in an app crash in debug mode. | ||
| - **Unique Timestamps:** Having unique timestamps for events is crucial for maintaining accurate and reliable data. Ensure that events do not share the same timestamp down to the millisecond level. |
There was a problem hiding this comment.
I would interpret this as do not track events at the same millisecond. Are we trying to say this here?
Not sure what this means.
| Ensure your events adhere to the following rules to maintain data integrity and prevent rejected payloads: | ||
|
|
||
| - **Consistent Data Types:** Track event attributes without changing their data types across updates or platforms. For example, if `price` is tracked as a number in your iOS app, it must also be tracked as a number in the Android SDK, not as a string. MoEngage SDK detects data types automatically unless explicitly specified as a string. | ||
| - **Event Formatting:** Event names and attributes should not contain any special characters other than underscores (`_`). Spaces and underscores are permitted. |
There was a problem hiding this comment.
Why is this only in iOS?
| - **Consistent Data Types:** Track event attributes without changing their data types across updates or platforms. For example, if `price` is tracked as a number in your iOS app, it must also be tracked as a number in the Android SDK, not as a string. MoEngage SDK detects data types automatically unless explicitly specified as a string. | ||
| - **Event Formatting:** Event names and attributes should not contain any special characters other than underscores (`_`). Spaces and underscores are permitted. | ||
| - **Empty Attribute Names:** Passing an empty string (`""`) as an attribute name is **fatal** and will cause an **app crash** in Debug mode. Always provide a valid, non-empty string for attribute names. | ||
| - **Invalid Attribute Values:** The SDK rejects events with invalid attributes. Attribute values can only be Strings, Numbers, and Arrays (of strings or numbers). |
There was a problem hiding this comment.
In production, we reject only the attribute, not the event. Those attributes would be dropped.
| - **Event Formatting:** Event names and attributes should not contain any special characters other than underscores (`_`). Spaces and underscores are permitted. | ||
| - **Empty Attribute Names:** Passing an empty string (`""`) as an attribute name is **fatal** and will cause an **app crash** in Debug mode. Always provide a valid, non-empty string for attribute names. | ||
| - **Invalid Attribute Values:** The SDK rejects events with invalid attributes. Attribute values can only be Strings, Numbers, and Arrays (of strings or numbers). | ||
| - **Debug Mode Validation :** To protect backend data integrity, the SDK strictly validates event attributes in Debug mode. Passing unsupported values throws an exception and crashes the app. Common triggers include: |
There was a problem hiding this comment.
The validation is present in all modes. Debug mode throws a fatal exception.
| - Passing invalid numbers like `Double.nan` or `Infinity`. | ||
| - Passing empty Arrays or Dictionaries. | ||
| - Nesting `Date` or `MoEngageGeoLocation` objects inside an Array or Dictionary (these must be passed directly as values). | ||
| - **Timestamps:** Unique timestamps are crucial for maintaining accurate and reliable data. Ensure that multiple events do not share the exact same timestamp down to the millisecond. |
| - Passing empty Arrays or Dictionaries. | ||
| - Nesting `Date` or `MoEngageGeoLocation` objects inside an Array or Dictionary (these must be passed directly as values). | ||
| - **Timestamps:** Unique timestamps are crucial for maintaining accurate and reliable data. Ensure that multiple events do not share the exact same timestamp down to the millisecond. | ||
| - If you don’t have any attributes, just pass **nil** as the second argument. For eg. |
There was a problem hiding this comment.
why is this part of validation?
|
|
||
| <Info> | ||
| SDK adheres to the MoEngage FUP policies. For more information, refer to the [Fair Usage Policy](https://www.moengage.com/docs/user-guide/data/key-concepts/fair-usage-policy-fup). | ||
| - We track certain events by default in our SDK, so please make sure to use the default events instead of tracking a new event for the same scenarios. Find the list of default events tracked by SDK [here](https://www.moengage.com/docs/user-guide/getting-started/integration/default-android-sdk#default-events). |
There was a problem hiding this comment.
Why did we add this line? @shubhra-pati
|
|
||
| Ensure your events adhere to the following rules to maintain data integrity and prevent rejected payloads: | ||
|
|
||
| - **Supported Data Types:** MoEngage supports the following data types: `String`, `Integer`, `Long`, `Double`, `Float`, `Boolean`, `Date`, `GeoLocation`, `JSON Object`, and `JSON Array`. If any other data type is passed, the MoEngage SDK rejects that specific attribute (the rest of the event payload will still be tracked). Additionally, starting from SDK version **14.09.00**, passing an unsupported data type in an event property results in an app crash in debug mode. |
There was a problem hiding this comment.
What would happen in the release mode, and @msoumya-engg-sdk , should we mention the empty values or null here?
There was a problem hiding this comment.
@Keshav-MOE this should be same as iOS as well, @umangmoe please conform
There was a problem hiding this comment.
Additionally, starting from SDK version 14.09.00, passing an unsupported data type in an event property results in an app crash in debug mode.
Should be reworded as throws an UnsupportedOperationException.
There was a problem hiding this comment.
The SDK version is 13.6.00
There was a problem hiding this comment.
In the release build the attribute would be dropped.
There was a problem hiding this comment.
Added in 6f5f701d — release-build behavior is now explicit on this page: "In release builds, the SDK silently drops the specific invalid attribute and logs the issue. The rest of the event payload is still tracked." SDK version corrected to 13.6.00 per @msoumya-engg-sdk.
There was a problem hiding this comment.
Restructured in 6f5f701d — Android track-events.mdx now uses the same two-layer framing as iOS (naming/format rules + type validation). @umangmoe please confirm the framing reads correctly for Android.
There was a problem hiding this comment.
Corrected in 6f5f701d — version updated from 14.09.00 to 13.6.00.
There was a problem hiding this comment.
Added in 6f5f701d — Android section now reads: "In release builds, the SDK silently drops the specific invalid attribute and logs the issue. The rest of the event payload is still tracked."
There was a problem hiding this comment.
Addressed in 6f5f701d — version corrected to 13.6.00 and the line was rewritten into the new "Validations and restrictions" section with explicit Release/Debug behavior.
|
|
||
| - **Empty Attribute Names:** Passing an empty string (`""`) as an attribute name is fatal and will cause an app crash in Debug mode. Always provide a valid, non-empty string for attribute names. | ||
| - **Invalid Attribute Values:** The SDK validates event attributes in all modes. Attribute values can only be Strings, Numbers, Dictionaries, and Arrays (of strings or numbers). If an unsupported data type is passed, the SDK drops the specific invalid attribute (the rest of the event payload will still be tracked successfully). | ||
| - **Debug Mode Exceptions:** While production simply drops invalid attributes, passing unsupported values in Debug mode throws a fatal exception and crashes the app to help you identify data issues early. Common triggers for this crash include: |
There was a problem hiding this comment.
Same . we need to mention the behaviour of sdk in release notes
There was a problem hiding this comment.
Use DEBUG consistently across all documentation
There was a problem hiding this comment.
Let me know what you want me to add to the release notes.
| </CodeGroup> | ||
|
|
||
| <Warning> | ||
| The following portfolio attribute scenarios cause DEBUG crashes on iOS: |
There was a problem hiding this comment.
@msoumya-engg-sdk, what about the release build?
There was a problem hiding this comment.
@Keshav-MOE in these scenarios attribute is dropped in release build
There was a problem hiding this comment.
Updated in 6f5f701d. The Warning header on sdk-initialization.mdx now reads: "In Release and TestFlight builds, the invalid configuration or attribute is dropped silently and logged."
Mintlify-Source: dashboard-editor
Mintlify-Source: dashboard-editor
Mintlify-Source: dashboard-editor
Mintlify-Source: dashboard-editor
| The following portfolio attribute scenarios cause DEBUG crashes on iOS: | ||
|
|
||
| - If you set _any_ portfolio attribute during SDK initialization without passing a valid `projectID`, the SDK throws an exception, resulting in an application crash in _Debug_ mode. If you are using portfolio attributes, you must provide the `projectConfig`. | ||
| - If the `USER_ATTRIBUTE_UNIQUE_ID` is set at the portfolio level, the application will **always** crash in Debug mode, regardless of whether a `projectID` is passed or not. |
There was a problem hiding this comment.
Why are we talking about user attributes in initialization? At this point, the developer does not even know what USER_ATTRIBUTE_UNIQUE_ID is.
They use a method to pass the attribute they don't even know the attribute name
There was a problem hiding this comment.
shall i move this to track user attribute file?
There was a problem hiding this comment.
The user-attribute content has been kept on tracking-user-attributes.mdx and consolidated into a new "Validations and restrictions" section there (same two-layer framing as the events page). The sdk-initialization.mdx Warning now only covers init-time validations (empty Workspace ID, portfolio + projectID, SDK downgrade, API calls before init) — no user-attribute content.
| <Warning> | ||
| The following portfolio attribute scenarios cause DEBUG crashes on iOS: | ||
|
|
||
| - If you set _any_ portfolio attribute during SDK initialization without passing a valid `projectID`, the SDK throws an exception, resulting in an application crash in _Debug_ mode. If you are using portfolio attributes, you must provide the `projectConfig`. |
There was a problem hiding this comment.
SDK does not validate the project id in any sense apart from it not being null or empty string.
There was a problem hiding this comment.
Any portfolio attribute set when the SDK was initialized without a project code → crash.
Based on the above, I added this. Shall I remove the same?
There was a problem hiding this comment.
@shubhra-pati update passing a valid projectID -> passing a non-empty projectID
…n iOS documentation
|
|
||
| - **Empty Attribute Names:** Passing an empty string (`""`) as an attribute name is fatal and will cause an app crash in _Debug_ mode. Always provide a valid, non-empty string for attribute names. | ||
| - **Invalid Attribute Values:** The SDK validates event attributes in all modes. Attribute values can only be Strings, Numbers, Dictionaries, and Arrays (of strings or numbers). If an unsupported data type is passed, the SDK drops the specific invalid attribute (the rest of the event payload will still be tracked successfully). | ||
| - **Debug Mode Exceptions:** While production simply drops invalid attributes, passing unsupported values in _Debug_ mode throws a fatal exception and crashes the app to help you identify data issues early. Common triggers for this crash include: |
There was a problem hiding this comment.
Please correct this as below
Debug Mode Exceptions: Release and TestFlight builds silently drop unsupported values and log them, while Debug builds throw a fatal exception and crash the app to surface data issues early in development. Common triggers for this crash include
There was a problem hiding this comment.
Updated in 6f5f701d. The "Supported attribute value types" section now reads: "In DEBUG builds, the SDK throws a fatal exception and crashes the app to surface data issues early in development. In Release and TestFlight builds, the SDK silently drops the specific invalid attribute and logs the issue."
| Clicked events should be reported when a user clicks on any element that has been personalized using the response of the Personalize API. | ||
|
|
||
| <Warning> | ||
| When calling `experienceClicked()`, the `experienceAttribute` dictionary is strictly validated. The `experienceAttribute` dictionary must contain both `"cid"` and "experience." Missing any of these keys, or passing an invalid Workspace ID, the SDK throws an exception, resulting in an application crash in _Debug_ mode. |
There was a problem hiding this comment.
Update passing an invalid Workspace ID to passing an un-initialized Workspace ID
There was a problem hiding this comment.
Reworded in 6f5f701d — the Workspace ID phrasing was tightened to use "un-initialized Workspace ID" (per @msoumya-engg-sdk on the related thread) instead of describing it as a validation rule.
There was a problem hiding this comment.
Applied in 6f5f701d — the Warning now reads: "the call is made against an un-initialized Workspace ID".
| </Info> | ||
| Ensure your events adhere to the following rules to maintain data integrity and prevent issues: | ||
|
|
||
| - **Empty Attribute Names:** Passing an empty string (`""`) as an attribute name is fatal and will cause an app crash in _Debug_ mode. Always provide a valid, non-empty string for attribute names. |
There was a problem hiding this comment.
Remove valid, SDK doesn't validate anything on name other than its non-empty.
There was a problem hiding this comment.
Resolved in earlier restructure — "valid" was dropped when this section was rewritten into the two-layer framing. The naming rule now reads only: "Attribute names must be non-empty."
| Ensure your events adhere to the following rules to maintain data integrity and prevent issues: | ||
|
|
||
| - **Empty Attribute Names:** Passing an empty string (`""`) as an attribute name is fatal and will cause an app crash in _Debug_ mode. Always provide a valid, non-empty string for attribute names. | ||
| - **Invalid Attribute Values:** The SDK validates event attributes in all modes. Attribute values can only be Strings, Numbers, Dictionaries, and Arrays (of strings or numbers). If an unsupported data type is passed, the SDK drops the specific invalid attribute (the rest of the event payload will still be tracked successfully). |
There was a problem hiding this comment.
Dictionaries -> Dictionaries (with string keys and supported values)
Arrays (of strings or numbers) -> Arrays (of supported values)
There was a problem hiding this comment.
Updated in 6f5f701d — the supported types line now reads: "Dictionary (with string keys and supported values), or Array (of supported values)".
| - **Debug Mode Exceptions:** While production simply drops invalid attributes, passing unsupported values in _Debug_ mode throws a fatal exception and crashes the app to help you identify data issues early. Common triggers for this crash include: | ||
| - Passing `null` (`NSNull()`). | ||
| - Passing custom models or UI elements (e.g., `UIColor`, `UIImage`). | ||
| - Passing invalid numbers like `Double.nan` or `Infinity`. |
There was a problem hiding this comment.
Double.nan -> NaN
There was a problem hiding this comment.
Changed in 6f5f701d — Double.nan → NaN in both tracking-events.mdx and tracking-user-attributes.mdx.
| NSE enables rich push notifications (including images, video, and GIFs) and tracks notification impressions across all app states. | ||
|
|
||
| <Warning> | ||
| Verify that the Notification Service Extension is properly configured and the MoEngage RichNotification extension is integrated into your iOS project. If a device receives a rich push notification payload without this integration in place, the SDK throws an exception, resulting in an application crash in _Debug_ mode. |
There was a problem hiding this comment.
MoEngage RichNotification extension -> MoEngageRichNotification framework
There was a problem hiding this comment.
Fixed in 6f5f701d — now MoEngageRichNotification framework (no space).
| </CodeGroup> | ||
|
|
||
| <Warning> | ||
| If you set any portfolio attribute during SDK initialization without passing a non-empty `projectID`, the SDK throws an exception, resulting in an application crash in _Debug_ mode. If you are using portfolio attributes, you must provide the `projectConfig`. |
There was a problem hiding this comment.
The messaging is bit confusing, may be:
If you set any portfolio attribute without passing a non-empty
projectIDduring SDK initialization , the SDK throws an exception, resulting in an application crash in Debug mode. If you are using portfolio attributes, you must provide theprojectConfig.
There was a problem hiding this comment.
Applied verbatim in 6f5f701d. The portfolio bullet now reads: "If you set any portfolio attribute without passing a non-empty projectID during SDK initialization, the SDK throws an exception, resulting in an application crash in DEBUG mode. If you are using portfolio attributes, you must provide the projectConfig."
|
@Keshav-MOE @shubhra-pati let's clarify what we mean by debug build as well. In context of iOS Debug build means:
This will help as customer might confuse it with app distributed with debugging mode, which is not the case. |
|
Additional debug crashes missing:
|
umangmoe
left a comment
There was a problem hiding this comment.
Why don't we have parity between Android and iOS updates?
The personalization APIs exist in Android as well, exception thrown is missing in that.
| A Live Activity instance can be started remotely via a push or locally from the app. | ||
|
|
||
| <Warning> | ||
| Starting a Live Activity before the MoEngage SDK has fully initialized triggers an exception and causes your app to crash in _Debug_ mode. Ensure the SDK is initialized before calling any Live Activity tracking methods. |
There was a problem hiding this comment.
What is meant by fully initialized?
There isn't any partial initialization. How will a developer validate full initialization?
There was a problem hiding this comment.
Reworded in 6f5f701d — the Warning now reads: "Live Activity tracking methods must be called only once the SDK is initialized. Calling them earlier — for example, before the initializer runs in application(_:didFinishLaunchingWithOptions:) — throws a fatal exception..." Removed the "fully initialized" phrasing.
- Restructure iOS event/user-attribute validations into two-layer framing (naming/format vs type), align Android validations to match - Standardize DEBUG terminology and clarify Release/TestFlight drop+log behavior across all warnings - Add iOS DEBUG mode definition (TEST workspace + Xcode) - Cover additional debug-mode crash scenarios from SDK team: empty Workspace ID, SDK downgrade, API calls before init, encryption key/keychain group, IDFA without AdSupport, JWT without enabling, duplicate Live Activity trackStarted - Apply SME wording corrections (NaN, MoEngageRichNotification, un-initialized Workspace ID, projectID phrasing, Android SDK version 13.6.00) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

This PR contains the doc update changes wrt crashes in debug mode feedback.
Mintlify
0 threads from 0 users in Mintlify