Loyalty in mobile SDK covers two features: - [Promotions](/developers/mobile-sdk/loyalty#promotions) - In Synerise, Promotions lets you: - introduce a system of awarding and spending loyalty points so your profiles can use them and purchase your products. - use promotions as a distribution channel for discounted products.
Read more about [implementing promotions in your store](/docs/ai-hub/promotions/introduction-to-promotions).
- [Vouchers](/developers/mobile-sdk/loyalty#vouchers) - In Synerise, you can create a pool of discount codes which you can distribute through the mobile application.
Read more about [voucher pools](/docs/assets/code-pools).
## Promotions --- ### Overview {id=promotions-overview} Promotions let you fetch special offers for your profiles.
Documentation on how to prepare promotions is available [here](/docs/ai-hub/promotions/creating-promotions).
**Class reference** for promotions: [Android](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#promotions), [iOS](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers#promotions), [React Native](/developers/mobile-sdk/class-reference/react-native/promotions-and-vouchers#promotions), [Flutter](/developers/mobile-sdk/class-reference/flutter/promotions-and-vouchers#promotions). **Method reference** for promotions: [Android](/developers/mobile-sdk/method-reference/android/promotions), [iOS](/developers/mobile-sdk/method-reference/ios/promotions), [React Native](/developers/mobile-sdk/method-reference/react-native/promotions), [Flutter](/developers/mobile-sdk/method-reference/flutter/promotions). ### Basic implementation {id=promotions-basic-implementation} The example below is the basic implementation and retrieves all promotions for a profile, without any parameters to filter them.
```java IDataApiCall apiCall = Promotions.getPromotions(); apiCall.execute(onSuccess, showAlertError); ```
```kotlin val apiCall = Promotions.getPromotions() apiCall.execute(onSuccess, showAlertError) ```
```swift Promotions.getPromotions(success: { (promotionResponse) in //success }) { (error) in //failure } ```
```objective-c [SNRPromotions getPromotionsWithSuccess:^(SNRPromotionResponse *promotionResponse) { //success } failure:^(NSError *error) { //failure }]; ```
```javascript Synerise.Promotions.getAllPromotions( function(promotionResponse) { //success }, function(error) { //failure } ) ```
```dart PromotionResponse promotionResponse = await Synerise.promotions.getAllPromotions().catchError((error) { //failure }); ```
### Advanced implementation {id=promotions-advanced-implementation} If you want to have full possibilities of configuring the query for promotions, getting items using the `PromotionsApiQuery` is the best way to achieve it. The table explains the filtering options available when fetching promotions.
| Property | Type | Default | Description | | --- | --- | --- | --- | | statuses | [`List`](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#promotionstatus) | [] | List of statuses for query | | types | [`List`](/developers/mobile-sdk/class-reference/android/promotions-and-vouchers#promotiontype) | [] | List of types for query | | sortParameters | `LinkedHashMap` | [] | Specifies [sorting rules](#promotion-sorting-options) for items in the response | | limit | `Int` | 100 | Limit of items per page in the response | | page | `Int` | 1 | Page number | | includeMeta | `Boolean` | false | Specifies if metadata should be included in the response |
| Property | Type | Default | Description | | --- | --- | --- | --- | | statuses | [`[PromotionStatus]`](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers/#promotionstatus) | [] | List of statuses for query | | types | [`[PromotionType]`](/developers/mobile-sdk/class-reference/ios/promotions-and-vouchers/#promotiontype) | [] | List of types for query | | sorting | `[[SNRPromotionSortingKey: SNRApiQuerySortingOrderString]]` | [] | Specifies [sorting rules](#promotion-sorting-options) for items in the response | | limit | `Int` | 100 | Limit of items per page in the response | | page | `Int` | 1 | Page number | | includeMeta | `Bool` | false | Specifies if meta data should be included in the response |
| Property | Type | Default | Description | | --- | --- | --- | --- | | statuses | [`Array`](/developers/mobile-sdk/class-reference/react-native/promotions-and-vouchers#promotionstatus) | [] | List of statuses for query | | types | [`Array`](/developers/mobile-sdk/class-reference/react-native/promotions-and-vouchers#promotiontype) | [] | List of types for query | | sorting | `Array` | [] | Specifies [sorting rules](#promotion-sorting-options) for items in the response | | limit | `number` | 100 | Limit of items per page in the response | | page | `number` | 1 | Page number | | includeMeta | `boolean` | false | Specifies if meta data should be included in the response |
| Property | Type | Default | Description | | --- | --- | --- | --- | | statuses | [`List`](/developers/mobile-sdk/class-reference/flutter/promotions-and-vouchers#promotionstatus) | [] | List of statuses for query | | types | [`List`](/developers/mobile-sdk/class-reference/flutter/promotions-and-vouchers#promotiontype) | [] | List of types for query | | sorting | `List` | [] | Specifies [sorting rules](#promotion-sorting-options) for items in the response | | limit | `int` | 100 | Limit of items per page in the response | | page | `int` | 1 | Page number | | includeMeta | `bool` | false | Specifies if meta data should be included in the response |
The example below is the advanced implementation and fetches promotions using `PromotionsApiQuery` object.
```java List statuses = new ArrayList<>(); if (activeBox.isChecked()) statuses.add(PromotionStatus.ACTIVE); if (assignedBox.isChecked()) statuses.add(PromotionStatus.ASSIGNED); if (redeemedBox.isChecked()) statuses.add(PromotionStatus.REDEEMED); List types = new ArrayList<>(); if (generalBox.isChecked()) types.add(PromotionType.GENERAL); if (customBox.isChecked()) types.add(PromotionType.CUSTOM); if (membersOnlyBox.isChecked()) types.add(PromotionType.MEMBERS_ONLY); PromotionsApiQuery query = new PromotionsApiQuery(); query.limit = 100; query.statuses = statuses; query.types = types; query.page = page; query.includeMeta = includeButton.isChecked(); LinkedHashMap sortParams = new LinkedHashMap<>(); sortParams.put(PromotionSortingKey.TYPE, ApiQuerySortingOrder.ASCENDING); sortParams.put(PromotionSortingKey.CREATED_AT, ApiQuerySortingOrder.ASCENDING); sortParams.put(PromotionSortingKey.EXPIRE_AT, ApiQuerySortingOrder.DESCENDING); query.setSortParameters(sortParams); IDataApiCall apiCall = Promotions.getPromotions(query); apiCall.execute(onSuccess, new DataActionListener() { @Override public void onDataAction(ApiError apiError) { // error handling } }); ```
```kotlin val statuses = ArrayList() if (activeBox.isChecked()) statuses.add(PromotionStatus.ACTIVE) if (assignedBox.isChecked()) statuses.add(PromotionStatus.ASSIGNED) if (redeemedBox.isChecked()) statuses.add(PromotionStatus.REDEEMED) val types = ArrayList() if (generalBox.isChecked()) types.add(PromotionType.GENERAL) if (customBox.isChecked()) types.add(PromotionType.CUSTOM) if (membersOnlyBox.isChecked()) types.add(PromotionType.MEMBERS_ONLY) val query = PromotionsApiQuery() query.limit = 100 query.statuses = statuses query.types = types query.page = page query.includeMeta = includeButton.isChecked() val sortParams = LinkedHashMap() sortParams.put(PromotionSortingKey.TYPE, ApiQuerySortingOrder.ASCENDING) sortParams.put(PromotionSortingKey.CREATED_AT, ApiQuerySortingOrder.ASCENDING) sortParams.put(PromotionSortingKey.EXPIRE_AT, ApiQuerySortingOrder.DESCENDING) query.setSortParameters(sortParams) val apiCall = Promotions.getPromotions(query) apiCall.execute(onSuccess, object:DataActionListener() { fun onDataAction(apiError:ApiError) { // error handling } }) ```
```swift let apiQuery = PromotionsApiQuery() apiQuery.types = [SNR_PROMOTION_TYPE_GENERAL] apiQuery.statuses = [SNR_PROMOTION_STATUS_ACTIVE, SNR_PROMOTION_STATUS_ASSIGNED] apiQuery.types = [SNR_PROMOTION_TYPE_GENERAL] apiQuery.sorting = [ [SNR_PROMOTION_SORTING_KEY_PRIORITY: SNR_API_QUERY_SORTING_ASC] ] apiQuery.limit = 50 apiQuery.page = 1 apiQuery.includeMeta = true Promotions.getPromotions(apiQuery: apiQuery, success: { (promotionResponse) in //success }, failure: { (error) in //failure }) ```
```objective-c SNRPromotionsApiQuery *apiQuery = [SNRPromotionsApiQuery new]; apiQuery.types = @[SNR_PROMOTION_TYPE_GENERAL]; apiQuery.statuses = @[SNR_PROMOTION_STATUS_ACTIVE, SNR_PROMOTION_STATUS_ASSIGNED]; apiQuery.types = @[SNR_PROMOTION_TYPE_GENERAL]; apiQuery.sorting = @[ @{ SNR_PROMOTION_SORTING_KEY_PRIORITY: SNR_API_QUERY_SORTING_ASC } ]; apiQuery.limit = 50; apiQuery.page = 1; apiQuery.includeMeta = YES; [SNRPromotions getPromotionsWithApiQuery:apiQuery success:^(SNRPromotionResponse *promotionResponse) { //success } failure:^(NSError *error) { //failure }]; ```
```javascript let apiQuery = new PromotionsApiQuery() apiQuery.statuses = [ PromotionStatus.Active ]; apiQuery.types = [ PromotionType.General ] apiQuery.sorting = [{ property: PromotionSortingKey.CreatedAt, order: ApiQuerySortingOrder.Ascending }] apiQuery.limit = 120 apiQuery.page = 2 apiQuery.includeMeta = true Synerise.Promotions.getPromotions(apiQuery, function(promotionResponse) { //success }, function(error) { //failure } ) ```
```dart List promotionsStatusList = [PromotionStatus.active]; List promotionTypeList = [PromotionType.general]; List apiQuerySortingList = [ApiQuerySorting(property: "", order: ApiQuerySortingOrder.ascending)]; PromotionsApiQuery promotionsApiQuery = PromotionsApiQuery( statuses: promotionsStatusList, types: promotionTypeList, sorting: apiQuerySortingList, limit: 10, page: 10, includeMeta: true ); PromotionResponse promotionResponse = await Synerise.promotions.getPromotions(promotionsApiQuery).catchError((error) { //failure }); ```
### Promotion type The promotion type options correspond to the [promotion type options available in the Synerise application](/docs/ai-hub/promotions/creating-promotions-for-entire-basket#type--limits) in the creating promotion form. - **GENERAL** - promotions are available to all profiles. - **MEMBERS_ONLY** - promotions are available to profiles who joined a loyalty program. - **HANDBILL** - promotions which can only be selected by the [AI promotion engine for a customer](/docs/ai-hub/personalized-promotions). - **CUSTOM** - custom promotions are a category that has custom configuration, tailored for chosen profiles. Constants in the SDK correlated with promotion types: | Android | iOS | React Native | Flutter | | --- | --- | --- | --- | | `PromotionType.GENERAL` | `SNR_PROMOTION_TYPE_GENERAL` | `PromotionType.General` | `PromotionType.general` | | `PromotionType.MEMBERS_ONLY` | `SNR_PROMOTION_TYPE_MEMBERS_ONLY` | `PromotionType.MembersOnly` | `PromotionType.membersOnly` | | `PromotionType.CUSTOM` | `SNR_PROMOTION_TYPE_CUSTOM` | `PromotionType.Custom` | `PromotionType.custom` | | `PromotionType.HANDBILL` | `SNR_PROMOTION_TYPE_HANDBILL` | `PromotionType.Handbill` | `PromotionType.handbill` | ### Promotion status - **ACTIVE** - promotion is activated by the profile. - **ASSIGNED** - promotion is assigned to a profile and visible to them. - **REDEEMED** - promotion is redeemed and finished for the profile. Constants in the SDK correlated with promotion statuses: | Android | iOS | React Native | Flutter | | --- | --- | --- | --- | | `PromotionStatus.ACTIVE` | `SNR_PROMOTION_STATUS_ACTIVE` | `PromotionStatus.Active` | `PromotionStatus.active` | | `PromotionStatus.ASSIGNED` | `SNR_PROMOTION_STATUS_ASSIGNED` | `PromotionStatus.Assigned` | `PromotionStatus.assigned` | | `PromotionStatus.REDEEMED` | `SNR_PROMOTION_STATUS_REDEEMED` | `PromotionStatus.Redeemed` | `PromotionStatus.redeemed` | ### Promotion sorting options You can set an array of sorting options. Each sorting option is a key-value pair. The key is the sorting key constant and the value is the sorting order. Promotion-related sorting constants: - **EXPIRE_AT** - time when the promotion expires. - **CREATED_AT** - time when the promotion was created. - **LASTING_AT** - time when the promotion stops being active for the profile. - **REQUIRE_REDEEMED_POINTS** - how many loyalty points are needed to redeem the promotion. - **UPDATED_AT** - time when the promotion was last updated. - **TYPE** - type of the promotion. - **PRIORITY** - priority of the promotion. Constants in the SDK correlated with promotion sorting options: | Android | iOS | React Native | Flutter | | --- | --- | --- | --- | | `PromotionSortingKey.EXPIRE_AT` | `SNR_PROMOTION_SORTING_KEY_EXPIRE_AT` | `PromotionSortingKey.ExpireAt` | `PromotionSortingKey.expireAt` | | `PromotionSortingKey.CREATED_AT` | `SNR_PROMOTION_SORTING_KEY_CREATED_AT` | `PromotionSortingKey.CreatedAt` | `PromotionSortingKey.createdAt` | | `PromotionSortingKey.LASTING_AT` | `SNR_PROMOTION_SORTING_KEY_LASTING_AT` | `PromotionSortingKey.LastingAt` | `PromotionSortingKey.lastingAt` | | `PromotionSortingKey.REQUIRE_REDEEMED_POINTS` | `SNR_PROMOTION_SORTING_KEY_REQUIRE_REDEEMED_POINTS` | `PromotionSortingKey.requireRedeemPoints` | `PromotionSortingKey.ExpireAt` | | `PromotionSortingKey.UPDATED_AT` | `SNR_PROMOTION_SORTING_KEY_UPDATED_AT` | `PromotionSortingKey.UpdatedAt` | `PromotionSortingKey.updatedAt` | | `PromotionSortingKey.TYPE` | `SNR_PROMOTION_SORTING_KEY_TYPE` | `PromotionSortingKey.Type` | `PromotionSortingKey.type` | | `PromotionSortingKey.PRIORITY` | `SNR_PROMOTION_SORTING_KEY_PRIORITY` | `PromotionSortingKey.Priority` | `PromotionSortingKey.priority` | You can sort each of the above ascending or descending by using the values: - **ASCENDING** - **DESCENDING** Constants in the SDK correlated with sorting order values: | Android | iOS | React Native | Flutter | | --- | --- | --- | --- | | `ApiQuerySortingOrder.ASCENDING` | `SNR_API_QUERY_SORTING_ASC` | `ApiQuerySortingOrder.Ascending` | `ApiQuerySortingOrder.ascending` | | `ApiQuerySortingOrder.DESCENDING` | `SNR_API_QUERY_SORTING_DESC` | `ApiQuerySortingOrder.Descending` | `ApiQuerySortingOrder.descending` | You can add a number of key-value pairs for sorting. ### Working with single promotions --- In addition to getting all promotions or a filtered list, you can get a single promotion. You can get a single promotion by: - UUID of the promotion - Code of the promotion These are the basic identity properties for a promotion. They are useful and thanks to them, you can **activate** and **deactivate** a single promotion too. The following methods are available: | Android | iOS | React Native | | --- | --- | --- | | [Get promotion identified by UUID](/developers/mobile-sdk/method-reference/android/promotions#get-promotion-by-uuid) | [Get promotion identified by UUID](/developers/mobile-sdk/method-reference/ios/promotions#get-promotion-by-uuid) | [Get promotion identified by UUID](/developers/mobile-sdk/method-reference/react-native/promotions#get-promotion-by-uuid) | | [Get promotion identified by code](/developers/mobile-sdk/method-reference/android/promotions#get-promotion-by-code) | [Get promotion identified by code](/developers/mobile-sdk/method-reference/ios/promotions#get-promotion-by-code) | [Get promotion identified by code](/developers/mobile-sdk/method-reference/react-native/promotions#get-promotion-by-code) | | [Activate promotion identified by UUID](/developers/mobile-sdk/method-reference/android/promotions#activate-promotion-by-uuid) | [Activates promotion identified by UUID](/developers/mobile-sdk/method-reference/ios/promotions#activate-promotion-by-uuid) | [Activates promotion identified by UUID](/developers/mobile-sdk/method-reference/react-native/promotions#activate-promotion-by-uuid) | | [Activate promotion identified by code](/developers/mobile-sdk/method-reference/android/promotions#activate-promotion-by-code) | [Activate promotion identified by code](/developers/mobile-sdk/method-reference/ios/promotions#activate-promotion-by-code) | [Activate promotion identified by code](/developers/mobile-sdk/method-reference/react-native/promotions#activate-promotion-by-code) | | [Activate promotions](/developers/mobile-sdk/method-reference/android/promotions#activate-promotions-in-a-batch) | [Activate promotions](/developers/mobile-sdk/method-reference/ios/promotions#activate-promotions-in-a-batch) | [Activate promotions](/developers/mobile-sdk/method-reference/react-native/promotions#activate-promotions-in-a-batch) | | [De-activate promotion identified by UUID](/developers/mobile-sdk/method-reference/android/promotions#deactivate-promotion-by-uuid) | [De-activate promotion identified by UUID](/developers/mobile-sdk/method-reference/ios/promotions#deactivate-promotion-by-uuid) | [De-activate promotion identified by UUID](/developers/mobile-sdk/method-reference/react-native/promotions#deactivate-promotion-by-uuid) | | [De-activate promotion identified by code](/developers/mobile-sdk/method-reference/android/promotions#deactivate-promotion-by-code) | [De-activate promotion identified by code](/developers/mobile-sdk/method-reference/ios/promotions#deactivate-promotion-by-code) |[De-activate promotion identified by code](/developers/mobile-sdk/method-reference/react-native/promotions#deactivate-promotion-by-code) | | [De-activate promotions](/developers/mobile-sdk/method-reference/android/promotions#deactivate-promotions-in-a-batch) | [De-activate promotions](/developers/mobile-sdk/method-reference/ios/promotions#deactivate-promotions-in-a-batch) | [De-activate promotions](/developers/mobile-sdk/method-reference/react-native/promotions#deactivate-promotions-in-a-batch) | ## Vouchers --- ### Overview {id=vouchers-overview} In Synerise, you can create a voucher pool to distribute discount codes to your profiles for the campaign purposes. The codes in a voucher pool get two forms: - a text string - a barcode
Before using it in your mobile app, [create a voucher pool in Synerise](/docs/assets/code-pools).
**Class reference** for vouchers: [Android](/developers/mobile-sdk/class-reference/android/modules#promotions), [iOS](/developers/mobile-sdk/class-reference/ios/modules#promotions), [React Native](/developers/mobile-sdk/class-reference/ios/modules#promotions), [Flutter](/developers/mobile-sdk/class-reference/flutter/modules#promotions). **Method reference** for vouchers: [Android](/developers/mobile-sdk/method-reference/android/promotions#vouchers), [iOS](/developers/mobile-sdk/method-reference/ios/promotions#vouchers), [React Native](/developers/mobile-sdk/method-reference/react-native/promotions#vouchers), [Flutter](/developers/mobile-sdk/method-reference/flutter/promotions#vouchers). ### Voucher status - **UNASSIGNED** - voucher is unassigned to any profile. - **ASSIGNED** - voucher is assigned to a profile and visible to them. - **REDEEMED** - voucher is redeemed and finished for the profile. - **CANCELED** - voucher is canceled for the profile. ### Working with vouchers The following methods are available: | Android | iOS | React Native | | --- | --- | --- | | [Get voucher code only once or assign a voucher with provided pool UUID for the profile](/developers/mobile-sdk/method-reference/android/promotions#get-or-assign-voucher-from-pool)| [Get voucher code only once or assign a voucher with provided pool UUID for the profile](/developers/mobile-sdk/method-reference/ios/promotions#get-or-assign-voucher-from-pool) |[Get voucher code only once or assign a voucher with provided pool UUID for the client](/developers/mobile-sdk/method-reference/react-native/promotions#get-or-assign-voucher-from-pool) | | [Assign voucher with provided pool UUID for the profile](/developers/mobile-sdk/method-reference/android/promotions#assign-voucher-code-from-pool) | [Assign voucher with provided pool UUID for the profile](/developers/mobile-sdk/method-reference/ios/promotions#assign-voucher-code-from-pool) | [Assign voucher with provided pool UUID for the profile](/developers/mobile-sdk/method-reference/react-native/promotions#assign-voucher-code-from-pool) | | [Get profile's voucher codes](/developers/mobile-sdk/method-reference/android/promotions#get-voucher-codes-assigned-to-customer) | [Get profile's voucher codes](/developers/mobile-sdk/method-reference/ios/promotions#get-voucher-codes-assigned-to-customer) | [Get profile's voucher codes](/developers/mobile-sdk/method-reference/react-native/promotions#get-voucher-codes-assigned-to-customer) |