Overview
Apple Wallet gives users a convenient way to organize and use rewards cards, boarding passes, tickets, and gift cards. You can bring up passes in your app with PassKit APIs, send them via email, or post them on the web. You can also set the time or location for an item to appear. With iOS 9, rewards cards can be enabled for Apple Pay.
Passes are a digital representation of information that might otherwise be printed on small pieces of paper or plastic. They let users take an action in the physical world. Passes can contain images and a barcode, and you can update passes using push notifications. The pass library contains the user’s passes, and users view and manage their passes using the Wallet app.
The Loyalty Apple Wallet service will enable you to download and update loyalty card and coupon passes on supported iOS devices.
API Reference
/{obfuscatedId}/coupon
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
/{obfuscatedId}/coupon
Gets apple coupon pass file for the supplied offer id
/{offerId}/updateCoupon
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
/{offerId}/updateCoupon
Update apple passbook pass files for the supplied offer id using Apple Push Notification Accepted scopes:
- 'sap.applewallet_manage' - Required to perform updates on passes which are already downloaded on devices
/{passType}/{objectId}/generateWalletUrl
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
/{passType}/{objectId}/generateWalletUrl
Generates a obfuscated URL to download a pass on the device. To generate a link for Loyalty Card send STORECARD as passtype and the loyalty memberId as the objectId. To generate a link for Loyalty Card send COUPON as passtype and the offerId of an active offer as the objectId. It is obligatory to inform the user that the user's iOS device push token would be stored on the SAP Hybris Loyalty server to support automatic update of passes. The user may choose not to receive the automatic updates by turning it off in the pass itself.
/{obfuscatedId}/loyaltycard
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
/{obfuscatedId}/loyaltycard
Gets Apple storecard pass file for the supplied member id
/{memberId}/updateLoyaltyCard
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
/{memberId}/updateLoyaltyCard
Updates Apple passbook pass files for the supplied member id using Apple Push Notification Accepted scopes:
- 'sap.applewallet_manage' - Required to perform updates on passes which are already downloaded on devices
Error Types
For more information about error codes, see the detailed error description for each API operation in API Reference. You can also check the standard error codes at API best practices.
Scopes
Scopes are strings that let you specify exactly what type of access you need to resources and operations in the Loyalty Apple Wallet service.
The table presents all the scopes supported by the Loyalty Apple Wallet service.
| Scope | Description |
|---|---|
| sap.applewallet_view | Use this scope to perform read only GET operations. |
| sap.applewallet_manage | Use this scope to perform POST,PUT,DELETE operations. |
Generate a passbook URL
Introduction
With the Loyalty Apple Wallet service you can do all the necessary operations to create a pass for a loyalty card or a coupon. This pass can then be added to Apple Wallet app on supported iOS devices. To perform the basic operations supported by the Loyalty Apple Wallet service, you need to be properly authorized. This is achieved through the header that carries the correct access token. The examples in this tutorial will lead you through those operations, showing what you need to provide to the methods, and what you get in return.
clientId = clientIdPlaceholder;
clientSecret = clientSecretPlaceholder;
tenant = projectIdPlaceholder;
client = appIdPlaceholder;
scopesRequired = 'hybris.tenant='+tenant+' sap.loyapplewallet_view sap.loyapplewallet_manage sap.loyapplewallet_delete';
token = tokenPlaceholder;
Get access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now get the token:
AccessToken = oAuth2Service.token.post({
'client_id' : clientId,
'client_secret': clientSecret,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': scopesRequired
});
access_token = AccessToken.body.access_token;
Create API client for Loyalty Apple Wallet service
API.createClient('appleWalletService',
'/services/loyaltyapplewallet/v1/api.raml');
Generate a download URL for a Loyalty Card Pass
The generated URL, if accessed from a supported iOS device will download a Loyalty Card passbook file.Please note that for the passbook to get generated, the card templates must be maintained properly for your project. Also the member id being passed must be a valid one. In this example we are passing a dummy value 1234567890. It is obligatory to inform the user that the user's iOS device push token would be stored on the SAP Hybris Loyalty server to support automatic update of passes. The user may choose not to receive the automatic updates by turning it off in the pass itself.
memberId = '1234567890'
appleWalletObj = appleWalletService.passType('STORECARD').objectId(memberId).generateWalletUrl.get(null, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-type' : 'application/json'
}
}
)
Generate a download URL for a Offer Coupon Pass
The generated URL, if accessed from a supported iOS device will download a Coupon passbook file.Please note that for the passbook to get generated, the coupon templates must be maintained properly for your project. Also the offer id being passed must be a valid one. In this example we are passing a dummy value 1234567890
offerId = '1234567890'
appleWalletObj = appleWalletService.passType('COUPON').objectId(offerId).generateWalletUrl.get(null, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-type' : 'application/json'
}
}
)
Update loyalty card and coupon passes
Introduction
In this tutorial we will go through the process of updating the passes which are already downloaded on the consumer's iOS devices. Apple Wallet supports an automatic updates of passes, if the consumer chooses to enable it on his or her iOS device. Loyalty Apple Wallet service lets you use this feature to silently update the passes which are already saved by the consumer.
To perform the basic operations supported by the Loyalty Apple Wallet service, you need to be properly authorized. This is achieved through the header that carries the correct access token. The examples in this tutorial will lead you through those operations, showing what you need to provide to the methods, and what you get in return.
clientId = clientIdPlaceholder;
clientSecret = clientSecretPlaceholder;
tenant = projectIdPlaceholder;
client = appIdPlaceholder;
scopesRequired = 'hybris.tenant='+tenant+' sap.loyapplewallet_view sap.loyapplewallet_manage sap.loyapplewallet_delete';
token = tokenPlaceholder;
Get access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now get the token:
AccessToken = oAuth2Service.token.post({
'client_id' : clientId,
'client_secret': clientSecret,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': scopesRequired
});
access_token = AccessToken.body.access_token;
Create API client for Loyalty Apple Wallet service
API.createClient('appleWalletService',
'/services/loyaltyapplewallet/v1/api.raml');
Update loyalty card passes
Consider the example where a consumer named Terry Jacobs registers with the loyalty program and saves the Loyalty Card into Apple Wallet app. Terry received 100 welcome points for signing up with the loyalty program.
Terry performs more activities which earns him more loyalty points. Since the loyalty card is already saved in the Wallet app, the points balance must be updated in the virtual loyalty card. The example code below shows us on how this can be achieved. Assuming that the memberId for Terry is 1234567890, we can call the updateLoyaltyCard endpoint to update all the loyalty card passes which Terry has saved in multiple supported devices.
When /updateLoyaltyCard is called by passing the memberId in the path variable, Loyalty Apple Wallet service sends a silent update ping via Apple Push Notification Service to all the registered devices of that member. Once device receives a silent push notification, the wallet app queries the Loyalty server to fetch the latest pass details and the pass is updated with latest information.
Please note that for the passbook to get generated, the card templates must be maintained properly for your project. Also the member id being passed must be a valid one. In this example we are passing a dummy value 1234567890.
memberId = '1234567890'
appleWalletObj = appleWalletService.memberId(memberId).updateLoyaltyCard.get(null, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-type' : 'application/json'
}
}
)
Update offer coupon passes
Consider the example where a consumer receives an offer and saves the offer as a coupon in the Apple Wallet app. The offer was later updated in the system with better description or it was updated by adding geomarketing attributes like geofence or iBeacons. The offer which was already saved in the iOS devices must now be updated so that the consumers who have already saved this offer do not miss out on the new changes.
The example code below shows us on how this can be achieved. Assuming that the offerId is 1234567890, we can call the updateCoupon endpoint to update all the coupon passes which the consumers have saved in their supported devices.
When /updateCoupon is called by passing the offerId in the path variable, Loyalty Apple Wallet service sends a silent update ping via Apple Push Notification Service to all the registered devices where the offer was saved previously. Once device receives a silent push notification, the wallet app queries the Loyalty server to fetch the latest pass details and the pass is updated with latest information.
Please note that for the passbook to get generated, the coupon templates must be maintained properly for your project. Also the offer id being passed must be a valid one. In this example we are passing a dummy value 1234567890.
offerId = '1234567890'
appleWalletObj = appleWalletService.offerId(offerId).updateCoupon.get(null, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-type' : 'application/json'
}
}
)
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.