Releases: talon-one/TalonOneJavaSdk
v4.5.0: Partial Returns & Collections
v4.5.0: Partial Returns & Collections
TBD
v4.4.1: Fix faulty string comparisons in ApiClient.java
v4.4.0: Customer Inventory Enhancements, Rule Failure Reasons and Import Endpoints
Summary
Management API
Expose import endpoints as integral part of the SDK
All of our CSV import endpoints are accessible via the Web Application from the corresponding entity pages (refer to our Help Center for an example regarding Coupons).
Now these are also available endpoints as part of the SDK (links to our developer docs):
Example code snippet demonstrating import coupons using a CSV file:
// ...preparing api client...
// An example could be seen at the repository's README file: https://github.com/talon-one/TalonOneJavaSdk#management-api
try {
Integer applicationId = 1;
Integer campaignId = 184;
File upFile = new File("path/to/coupons.csv");
ModelImport response = api.importCoupons(applicationId, campaignId, upFile);
} catch (FileNotFoundException e) {
System.out.println("CSV file was not found.");
e.printStackTrace();
} catch (Exception e) {
System.out.println("Error while importing coupons.");
System.out.println(e);
}
Introduce updateReferral
Endpoint
We introduced an endpoint to update referrals in order to allow updating their scheduling, usage limits and custom attributes attached to them.
Please consult the endpoint reference in our developer docs for more details.
Integration API
Improve Responses Transparency
We are constantly extending and improving our integration API to provide our consumers with the best transparency regarding what exactly has happened within their requests.
We have added new data points to our v2 endpoints effects in order to improve the transparency we aspire for:
- If an effect was triggered because of a specific coupon the effect will now include this coupon ID, see
Effect.md
- When a coupon is rejected we attach more details regarding the origin of the failure in
RejectCouponEffectProps
:conditionIndex
- The index of the condition that caused the rejection of the couponeffectIndex
- The index of the effect that caused the rejection of the coupondetails
- More details about the failure (if available)
- The same applies for referrals, when a referral is rejected we attach more details regarding the origin of the failure in
RejectReferralEffectProps
:conditionIndex
- The index of the condition that caused the rejection of the referraleffectIndex
- The index of the effect that caused the rejection of the referraldetails
- More details about the failure (if available)
Moreover, we have introduced a new response content, RuleFailureReasons
, which when requested will attach to the response a collection containing all failed rules, with details (see the RuleFailureReason
model to help narrowing down failures and further debugging efforts to a specific single condition or effect that caused the failure.
One "gotcha" to keep in mind: in order to maximize transparency, and due to the fact that we do not know in advance which campaign in the application the request targets, the list contains a collection of all failure reasons.
Meaning that, it might have "white noise" with data about failures that could be considered as "obvious" to the consumer. Therefore, we suggest always filtering the list by the campaign id that was expected to trigger and did not.
Extended Customer Inventory Endpoint
We have added a couple of useful data points to our customer inventory to make integration even simpler.
⚠️ ⚠️ It involves a breaking change when calling the operation
IntegrationApi apiInstance = new IntegrationApi(defaultClient);
String integrationId = "integrationId_example"; // String | The custom identifier for this profile, must be unique within the account.
Boolean profile = true; // Boolean | optional flag to decide if you would like customer profile information in the response
Boolean referrals = true; // Boolean | optional flag to decide if you would like referral information in the response
Boolean coupons = true; // Boolean | optional flag to decide if you would like coupon information in the response
Boolean loyalty = true; // Boolean | optional flag to decide if you would like loyalty information in the response
+Boolean giveaways = true; // Boolean | optional flag to decide if you would like giveaways information in the response
- CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons, loyalty);
+ CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons, loyalty, giveaways);
// ...
We are aware of the inconvenience, and as explained in #16, we are working on a better and improved implementation to avoid these breaking changes in the future.
As one can see, customer inventory now has the ability to return giveaway codes that belong to the profile in query.
In order to learn more about setting up such campaigns refer to this help center article and this developer docs tutorial.
We have also extended the coupons objects that are returned as part of the inventory and attached these two useful data-points to each returned coupon:
profileRedemptionCount
- holds the number of times the coupon was redeemed by the profilestate
- holds the state of the coupon and can be one of the below values:- active: reserved coupons that are neither pending nor used nor expired, and have a non-exhausted limit counter
- used: coupons that are not pending, and have reached their redemption limit or were redeemed by the profile before expiration
- expired: all non-pending, non-active, non-used coupons that were not redeemed by the profile
- pending: coupons that have a start date in the future
Attach Loyalty Program ID in responses
When the consumer requires that the response will contain the details of loyalty programs involved in processing the requests, we now attach the identifier of the loyalty program to the returned LoyaltyProgramLedgers
models.
The idea behind attaching the identifier is to help streamline further potential requests to our Management API with regard to details about a Loyalty Program, for example getLoyaltyStatistics or getLoyaltyPoints, that require the program identifier as part of the URI of the endpoint.
⚠️ A reminder of The Deprecation Notice: Integration API@v1 endpoints
The deprecation was introduced already in the last release of the SDK, here is a kind reminder of the deprecation notices for Integration API@v1 endpoints:
These endpoints will be flagged deprecated on 15.07.2021, meaning support for requests to these endpoints will end on that date. **We will not remove the...
v4.3.1: Introduce `triggeredByCoupon` property for Effects
Summary
Integration API
Introducing property triggeredByCoupon
on Effect
entities returned from our integration API, which holds the id
of the related coupon.
This should increase observability and allow to make deductions with regard to whether an effect was triggered directly by a coupon.
In order to match the coupon from the property, pass coupons
as part of the responseContent
array passed to the /v2/customer_session
endpoint. Then you would be able to lookup the id
of the returned coupons and match the corresponding one to the property from the new field triggeredByCoupon
.
v4.3.0: Multiple personal coupons creation endpoint, Loyalty related counters and Export Endpoints
Summary
Management API
Introduce createCouponsForMultipleRecipients
An endpoint/operation to allow creation of multiple coupons of the same configuration for up to 1,000 recipients at once.
Expose our export endpoints as integral part of the SDK
All of our CSV export operations are accessible via the Web Application from the corresponding entity pages (refer to our Help Center for an example regarding Coupons).
Now these are also available operations as part of the SDK (links to our developer docs):
Example code snippet demonstrating consuming and printing the lines of a Customer Loyalty Balance Export using the java.nio.file.Files
package:
import java.io.File;
import java.nio.file.Files;
import one.talon.ApiClient;
import one.talon.api.ManagementApi;
import one.talon.model.*;
// ...preparing api client...
// An example could be seen at the repository's README file: https://github.com/talon-one/TalonOneJavaSdk#management-api
try {
String programID = "1"; // loyalty program identifier
File response = api.exportLoyaltyBalance(programID);
List<String> contents = Files.readAllLines(response.toPath());
System.out.println(contents);
} catch (Exception e) {
System.out.println(e);
}
Expose destroySession
Expose an already existed endpoint to allow destroying a bearer token used in the context of the management-api.
This endpoint imitates a "logout" operation and will make the attached token invalid for consequent requests.
Introduce loyalty effects related counters on Campaign entities
As part of the newly added budgets to campaigns (see relevant Help Center Section), we now count and expose four new counters on campaigns with regard to loyalty:
createdLoyaltyPointsCount
: Total number of loyalty points created by rules in this campaigncreatedLoyaltyPointsEffectCount
: Total number of loyalty point creation effects triggered by rules in this campaignredeemedLoyaltyPointsCount
: Total number of loyalty points redeemed by rules in this campaignredeemedLoyaltyPointsEffectCount
: Total number of loyalty point redemption effects triggered by rules in this campaign
⚠️ ⚠️ Breaking Change: Fix Campaign's discountCount
type from Integer to BigDecimal
Campaign's discountCount
counter property was all along calculated as a floating decimal number by our system.
From this release on the returned values will be floating decimals and not cut-off integers:
-**discountCount** | **Integer** | Total amount of discounts redeemed in the campaign. | [optional]
+**discountCount** | [**BigDecimal**](BigDecimal.md) | Total amount of discounts redeemed in the campaign. | [optional]
Integration API
⚠️ A reminder of The Deprecation Notice: Integration API@v1 endpoints
The deprecation was introduced already in the last release of the SDK, here is a kind reminder of the deprecation notices for Integration API@v1 endpoints:
These endpoints will be flagged deprecated on 15.07.2021, meaning support for requests to these endpoints will end on that date. We will not remove the endpoints, and they will still be accessible for you to use.
We highly encourage migrating to the correspondent v2 endpoints for easier and more granular integration, as well as new features support (See our developer docs section about API V2.0).
Misc: Bump junit from 4.13 to 4.13.1
As per Pull Request #17, we have bumped the version of the junit
library dependency to 4.13.1
, after an alert regarding a security vulnerability with the former 4.13
.
v4.2.0: Loyalty Programs pending points & statistics, Introducing Loyalty customer inventory, customer profiles v2 integration dry runs
⚠️ ⚠️ Breaking Changes and Future Plans
We are using the OpenAPI Generator of the OpenAPITools project in order to generate all of our SDKs, including this one.
Unfortunately, the current status of the project implementation for JAVA client is not of the same philosophy as ours, with regard to amending optional query parameters (adding / removing / reordering):
We believe (and assume) that such amendments should not break the API consumers' operation calls, and are relying on that assumption while developing and implementing our APIs.
We are evaluating how to address the situation, and find a more robust and seamless approach to generate our Java SDK in the future.
While we are doing so, we wish to allow our SDK's consumers access to latest API changes and features, and therefore we will continue to publish versions to our SDK, including the current paradigm, which is breaking change on such changes to query parameters.
We are apologizing for the temporary inconvenience and will do our best to minimize such changes and take it into account while introducing those.
As well will we curate a list of those changes when they take place in the release notes, starting this release.
Please try to get yourself informed with those changes before updating your SDK version in your code base and make sure that the new version doesn't introduce breaking changes to your implementation.
Management API
getApplicationCustomers
ManagementApi apiInstance = new ManagementApi(defaultClient);
Integer applicationId = 56; // Integer |
+ String integrationId = "integrationId_example"; // String | Filter results performing an exact matching against the profile integration identifier.
+ Integer pageSize = 56; // Integer | The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
+ Integer skip = 56; // Integer | Skips the given number of items when paging through large result sets.
+ Boolean withTotalResultSize = true; // Boolean | When this flag is set, the result will include the total size of the result, across all pages. This might decrease performance on large data sets. With this flag set to true, hasMore will be be true whenever there is a next page. totalResultSize will always be zero. With this flag set to false, hasMore will always be set to false. totalResultSize will contain the total number of results for this query.
- InlineResponse20012 result = apiInstance.getApplicationCustomers(applicationId);
+ InlineResponse20012 result = apiInstance.getApplicationCustomers(applicationId, integrationId, pageSize, skip, withTotalResultSize);
// ...
getApplicationSessions
ManagementApi apiInstance = new ManagementApi(defaultClient);
Integer applicationId = 56; // Integer |
// ...
+ OffsetDateTime createdBefore = new OffsetDateTime(); // OffsetDateTime | Only return events created before this date
+ OffsetDateTime createdAfter = new OffsetDateTime(); // OffsetDateTime | Only return events created after this date
// ...
- InlineResponse20016 result = apiInstance.getApplicationSessions(applicationId, pageSize, skip, sort, profile, state, coupon, referral, integrationId, customerId);
+ InlineResponse20016 result = apiInstance.getApplicationSessions(applicationId, pageSize, skip, sort, profile, state, createdBefore, createdAfter, coupon, referral, integrationId);
// ...
getCampaigns
ManagementApi apiInstance = new ManagementApi(defaultClient);
Integer applicationId = 56; // Integer |
// ...
+ Integer campaignGroupId = 56; // Integer | Filter results to campaigns owned by the specified campaign group ID.
- InlineResponse2002 result = apiInstance.getCampaigns(applicationId, pageSize, skip, sort, campaignState, name, tags, createdBefore, createdAfter);
+ InlineResponse2002 result = apiInstance.getCampaigns(applicationId, pageSize, skip, sort, campaignState, name, tags, createdBefore, createdAfter, campaignGroupId);
// ...
getCustomerProfile
ManagementApi apiInstance = new ManagementApi(defaultClient);
- Integer applicationId = 56; // Integer |
Integer customerId = 56; // Integer |
- ApplicationCustomer result = apiInstance.getCustomerProfile(applicationId, customerId);
+ ApplicationCustomer result = apiInstance.getCustomerProfile(customerId);
// ...
Integration API
getCustomerInventory
IntegrationApi apiInstance = new IntegrationApi(defaultClient);
String integrationId = "integrationId_example"; // String | The custom identifier for this profile, must be unique within the account.
Boolean profile = true; // Boolean | optional flag to decide if you would like customer profile information in the response
Boolean referrals = true; // Boolean | optional flag to decide if you would like referral information in the response
Boolean coupons = true; // Boolean | optional flag to decide if you would like coupon information in the response
+ Boolean loyalty = true; // Boolean | optional flag to decide if you would like loyalty information in the response
- CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons);
+ CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons, loyalty);
// ...
updateCustomerProfileV2
IntegrationApi apiInstance = new IntegrationApi(defaultClient);
- String customerProfileId = "customerProfileId_example"; // String | The custom identifier for this profile, must be unique within the account.
- NewCustomerProfile body = new NewCustomerProfile(); // NewCustomerProfile |
+ String integrationId = "integrationId_example"; // String | The custom identifier for this profile, must be unique within the account.
+ CustomerProfileIntegrationRequestV2 body = new CustomerProfileIntegrationRequestV2(); // CustomerProfileIntegrationRequestV2 |
+ Boolean runRuleEngine = true; // Boolean | Flag to indicate whether to run the rule engine (Defaults to false).
+ Boolean dry = true; // Boolean | Flag to indicate whether to skip persisting the changes or not (Will not persist if set to 'true'. Only used when 'runRuleEngine' is set to 'true').
- CustomerProfileUpdate result = apiInstance.updateCustomerProfileV2(customerProfileId, body);
+ IntegrationStateV2 result = apiInstance.updateCustomerProfileV2(integrationId, body, runRuleEngine, dry);
// ...
❗ Please Notice: All those additional optional parameters could be simply sent with null
to represent the lack of them (instead of ""
for String parameters or false
for Boolean parameters)
Summary
Integration API
- Introduce
loyalty
flag ingetCustomerInventory
endpoint to retrieve also profile's loyalty programs subscription and stats upon querying the endpoint - Introduce flags to control whether a customer profile update request v2 should be a "dry run" or force it to "run rule engine"
⚠️ Deprecation Notice: Integration API@v1 endpoints
This version also introduced the deprecation notices for Integration API@v1 endpoints:
These endpoints will be flagged deprecated on 15.07.2021, meaning support for requests to these endpoints will end on that date. We will not remove the endpoints, and they will still be accessible for you to use.
We do encourage migrating to the correspondent v2 endpoints for easier and more granular integration, as well as new features support (See our developer docs section about API V2.0).
Loyalty Programs
Introduce Loyalty Program pending points, points that belong to the program's balance but will become active in the future:
- Introduce Loyalty Program setting to control default points' pending duration
- Introduce a couple of new attributes to communicate better a ledger's points status (pending, active, expired and spent)
- Introduce Loyalty Programs statistics endpoint to get a loyalty program stats snapshot
⚠️ ⚠️ Breaking Change: Loyalty Program points addition payload
This version also introduced the ability to set both loyalty points pending and validity durations.
In order to communicate these more clear, we have renamed the former `expir...
v4.1.1: Fix `LoyaltyLedgerEntry` parsing from API
- Fix
LoyaltyLedgerEntry
'stype
property values, failing to parse when retrieving values from the API - Flag API operations that return total count in their name for better visibility
v4.1.0: Dry Runs & Coupons discount limits
- Introduce "dry runs" for Integration API endpoints (See more details below)
- Add support to retrieve coupons as part of requesting customer profile inventories
- Add support for setting the
discountLimit
when creating or editing coupons
Introduce "dry runs" for Integration API endpoints
You can read more about the concept and where this feature could apply in your integration and workflow in our developers documentation center: https://developers.talon.one/Integration-API/dry-requests
Please Notice that all current integration request operations (trackEvent
, updateCustomerProfile
, updateCustomerSession
, updateCustomerSessionV2
) expects a boolean flag to determine whether this request is a dry run or not.
See code examples in the README.md as for reference.
v4.0.0: Integration API V2
- Replace code generator to OpenAPITools generator@v.4.2.3
- Add our new v2 integration api endpoint for customer sessions. Read more here: https://developers.talon.one/Getting-Started/APIV2
- Add v2-related management endpoints for managing AdditionalCosts
⚠️ Breaking Change: Please notice the new distinction between integration_auth
and api_key_v1
authentication strategies
From version 4.0.0 onwards, the integration_auth
strategy will be use for legacy HMAC authentication only (in deprecation process).
For the correct usage of this strategy, please consult this piece of code in the README file.
If until today you used the integration_auth
while initiating your ApiClient
instance and set the api-key and prefix as advised before:
ApiClient iApiClient = new ApiClient("integration_auth");
IntegrationApi iApi = new IntegrationApi(iApiClient );
// Setup: basePath, apiKeyPrefix and apiKey
iApi.getApiClient().setBasePath("https://mycompany.talon.one");
iApi.getApiClient().setApiKeyPrefix("ApiKey-v1");
iApi.getApiClient().setApiKey("dbc644d33aa74d582bd9479c59e16f970fe13bf34a208c39d6c7fa7586968468");
// ...
Please notice that you will have to pass the api_key_v1
strategy from now on, the rest of the code could be used as before:
- ApiClient iApiClient = new ApiClient("integration_auth");
+ ApiClient iApiClient = new ApiClient("api_key_v1");
// ... no change
v3.5.0
- Expose new profile inventory endpoint. Consult our developer docs for more information: https://developers.talon.one/Integration-API/API-Reference#getCustomerInventory
- Expose more attributes handling endpoints (create, update, get all)
copyCampaignToApplications
endpoint extended and now allows to override original campaign's description scheduling details and tags as part of the copy functionality. See parameters here: https://developers.talon.one/Management-API/API-Reference#copyCampaignToApplications