Implementing ATW button
add to wallet atw functionality into your system, you need to embed the provided atw script and configure it using tokenized card data this allows users to securely add digital cards to samsung wallet follow the steps below to implement the atw button script composition begin by composing the integration script using the sample code provided on the partners portal alternatively, refer to the integration sample code for detailed instructions create tokenized card data cdata next, generate the cdata tokenized card data and insert the corresponding cdata token into the script cdata represents the actual content of the wallet card and comes in various formats depending on the card type for more information, refer to the generate_cdata sample code note-cdata token should expire in 30 seconds after creation, so cdata token needs to be created right after users actually click ‘add to wallet’ button to implement ‘add to wallet’ button, you may need some base data you can find the base data and other necessary information on partner portal’s wallet card page samsung wallet on the web this section explains how to implement the add to wallet button using javascript within a web environment or web view web button reference with importing api javascript if you implement the "add to wallet" button using this script, the button is shown only on the devices that support samsung wallet to automatically parse <samsung wallet> html tags when the page is loaded, include the following standard javascript <script src="https //us-cdn-gpp mcsvc samsung com/lib/wallet-card js" type="text/javascript"></script> you can use these tags or javascript functions for the web button if you are rendering html and you have proper partner permissions you can also use the script by referring to the various attributes samsung wallet html tag the ‘samsung wallet’ namespace tag defines the placement and various attributes of the "add to wallet" web button for samsung wallet <samsung wallet cardid="card_id" cdata="cdata" partnercode="partner_code" buttonid="button_id" rdclickurl="rd_click_url" rdimpressionurl="rd_impression_url" ></samsung wallet> button attributes attribute description cardid string required wallet card identifier * value granted from the partners portal cdata string required encrypted card object json * this field needs to be encrypted * see security partnercode string required partner code * value granted from the partners portal buttonid string required dom element id for the "add to wallet" web button for samsung wallet buttontype string optional “add to wallet” button type [“btnsw” / “btnatsw” / “qrcode”, default btnsw] * see image resources inline string optional flag to display the "add to wallet" image button in one-line format default true one-line locale string optional locale of the "add to wallet" image button * see image resources rdclickurl string required url for logging a button click event * value granted from the partners portal rdimpressionurl string required url for logging a button impression event * value granted from the partners portal showforced string optional flag to force the "add to wallet" button to be displayed default false mediatheme string optional load the button’s resources from the media theme policy there are 4 themes default, inversion, lightonly, and darkonly default default *default load the button’s theme according to the prefers-color-scheme policy inversion load the inverse of the default button’s theme lightonly load the light theme of the default button *darkonly load the dark theme of the default button style string cssstyledeclaration optional load the button with custom style target string optional option to choose button’s target name * default “wallet” onshowbutton function optional callback handler function for the button’s on-show event onclickbutton function optional callback handler function for the button’s on-click event if you register the handler function, you must return a callback or promise value * see usage of onclickbutton handler samsungwallet addbutton function the samsungwallet addbutton function is used to explicitly render the add to wallet button on your web page using the samsung wallet javascript api samsungwallet addbutton { cardid "card_id", cdata "cdata", partnercode "partner_code", targetid "target_id", buttonid "button_id", rdclickurl "rd_click_url", rdimpressionurl "rd_impression_url", } button attributes attributes description cardid string required wallet card identifier * value granted from the partners portal cdata string required encrypted card object json * this field needs to be encrypted * seesecurity partnercode string required partner code * value granted from the partners portal targetid string required dom document object model element id to place the "add to wallet" web button for samsung wallet buttonid string required dom element id for the "add to wallet" web button for samsung wallet buttontype string optional “add to wallet” button type [“btnsw” / “btnatsw” / “qrcode”, default btnsw] * see image resources inline string optional flag to display the "add to wallet" image button in one-line format default true one-line locale string optional locale of the "add to wallet" image button * see image resources rdclickurl string required url of logging a button click event * value granted from the partners portal rdimpressionurl string required url of logging a button impression event * value granted from the partners portal showforced string optional flag to force the "add to wallet" button to be displayed default false mediatheme string optional load the button’s resources from the media theme policy there are 4 themes default, inversion, lightonly, and darkonly default default *default load the button’s theme according to the prefers-color-scheme policy *inversion load the inverse of the default button’s theme *lightonly load the light theme of the default button *darkonly load the dark theme of the default button style object cssstyledeclaration optional load the button with a custom style target string optional option to choose button’s target name * default “wallet” onshowbutton function optional callback handler function for the button’s on-show event onclickbutton function optional callback handler function for the button’s on-click event if you register the handler function, you must return a callback or promise value * see usage of onclickbutton handler usage of onclickbutton handler the onclickbutton handler allows to define what happens when a user clicks the ‘add to wallet’ button we recommend that you add the process of generating jwt cdata add cdata to options cdata to this handler, because of the cdata expiration time the function parameters are defined as follows attributes description options button attributes optional attributes of the current button callback function optional callback function to pass the flag to proceed default false promise resolve function optional promise-resolved value to pass the flag to proceed default false callback to web button process from callback attributes for es5 in an es5 ecmascript 5 environment, you can use the callback attribute in your web button implementation to control the flow of the "add to wallet" process by executing the callback function with a boolean flag {callback flag } you can determine whether or not to proceed to the next step in the wallet integration onclickbutton function options, callback { // todo partner's process callback flag } callback to web button process from returning promise for es6 in an es6 environment, by returning a promise with a resolving flag, you can proceed to the next add to wallet process onclickbutton async options => { return new promise async resolve, reject => { // todo partner's process await resolve flag } } note-the card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the ‘add to wallet’ button samsung wallet on the app this section outlines how to implement the “add to wallet” button within a native application e g , android or ios steps to implement ‘add to wallet’ in a native app download the official ‘add to wallet’ button graphics from the designated repository based on your service environment for details on available assets and usage guidelines, see the image resources section before displaying the button, use the ‘check service available devices’ api to determine whether the user's device supports samsung wallet interpret the api response as follows if "available" true → device is supported → show the ‘add to wallet’ button if "available" false → device is not supported → do not show the button implement a jwt web link on the button triggered action note-the card data token expires in 30 seconds after creation, so it needs to be created right after the user clicks the “add to wallet” button app button on android [sample code implementation] public class walletcodesample { protected final static string tag = "samsungwalletsample"; protected static final string host = "https //api-us3 mpay samsung com"; protected static final string path = "wallet/cmn/v2 0/device/available"; /** * sample entry point of the usage */ public static void main { executors newsinglethreadexecutor submit -> { final string modelname = build model; final string countrycode = null; // optional country code iso_3166-2 final string servicetype = "wallet"; // required, fixed for samsung wallet final string partnercode = null; // required try { walletcodesample sample = new walletcodesample ; boolean iswalletsupported = sample checkwalletsupported modelname, countrycode, servicetype, partnercode ; string msg = string format "query for model %s , countrycode %s , servicetype %s , partnercode %s / wallet supported? %s ", modelname, countrycode, servicetype, partnercode, iswalletsupported ; log d tag, msg ; } catch exception e { // failed to check due to some reasons log e tag, e getmessage , e ; } } ; } /** * please see the wallet api spec document > '6 6 check service available devices' for more details * * @return true if wallet supported, otherwise false * @throws exception throws exception when it's not possible to get status due to any reasons */ public boolean checkwalletsupported @nonnull string modelname, @nullable string countrycode, @nonnull string servicetype, @nonnull string partnercode throws exception { if modelname == null || modelname isempty { log e tag, "model name is required parameter" ; throw new exception "something went wrong failed to get device model name " ; } if servicetype == null || servicetype isempty { log e tag, "servicetype is required parameter" ; throw new exception "something went wrong failed to get device servicetype " ; } if partnercode == null || partnercode isempty { log e tag, "partnercode is required parameter" ; throw new exception "something went wrong failed to get device partnercode " ; } string urlstring = makeurl modelname, countrycode, servicetype ; log i tag, "urlstring " + urlstring ; try { url url = new url urlstring ; httpurlconnection connection = httpurlconnection url openconnection ; connection setrequestproperty "partnercode", partnercode ; connection setrequestmethod "get" ; int responsecode = connection getresponsecode ; log i tag, "responsecode " + responsecode ; bufferedreader bufferedreader; if responsecode == 200 { bufferedreader = new bufferedreader new inputstreamreader connection getinputstream ; } else { bufferedreader = new bufferedreader new inputstreamreader connection geterrorstream ; } stringbuilder sb = new stringbuilder ; string inputline; while inputline = bufferedreader readline != null { log i tag, inputline ; sb append inputline ; } connection disconnect ; bufferedreader close ; // parse result jsonobject jsonobject = new jsonobject sb tostring ; string resultcode = jsonobject getstring "resultcode" ; string resultmessage = jsonobject getstring "resultmessage" ; if "0" equals resultcode && "success" equals resultmessage { return jsonobject getboolean "available" ; } else { throw new exception "something went wrong, resultcode " + resultcode + " , resultmessage " + resultmessage + " " ; } } catch ioexception e { log e tag, e getmessage , e ; throw new exception "something went wrong ioexception , " + e getmessage ; } catch jsonexception e { log e tag, e getmessage , e ; throw new exception "something went wrong, receive wrong formatted response, " + e getmessage ; } } protected string makeurl @nonnull string modelname, @nullable string countrycode, @nonnull string servicetype { stringbuilder sb = new stringbuilder ; sb append host append '/' ; sb append path ; sb append '?' append "servicetype" append '=' append servicetype ; sb append '&' append "modelname" append '=' append modelname ; if countrycode != null && !countrycode isempty { sb append '&' append "countrycode" append '=' append countrycode ; } return sb tostring ; } } samsung wallet via mma or email this section outlines how to configure and deliver samsung wallet cards through mms or email, enabling users to add cards to samsung wallet directly from their messaging platforms overview integrating samsung wallet into mms or email involves sending a web link that allows users to add a wallet card without needing to load the full javascript api this approach is ideal for environments such as sms/mms messages email communications note-these methods do not support dynamically controlling button visibility based on device compatibility guide to configuring wallet code for email and mms messages set up the data fetch link, including the necessary server apis to retrieve the wallet card data create a unique ‘reference id’ for each transaction or request ensure the ‘reference id’ is complex and secure to prevent the inference of sensitive information send the message containing the web link via a preferred platform e g , email or mms for mms, the web link will show up as a ‘smart suggestion’ on samsung devices, providing a streamlined user experience for reference, a sample web link can be found on the wallet cards guide on the partners portal for card data, samsung wallet asks the partner system to provide card details through the server api duplicate requests are prohibited on the same device to ensure data integrity link to ‘add to wallet’ on mms/email** you can include an “add to wallet” web button in environments where the javascript api cannot be loaded, such as sms or email these methods do not support controlling “add to wallet” button visibility mms link url link url attributes description url string required “add to wallet” link url * see data transmit link * see data fetch link [email on web button link] <a href="url"> <img src="image_url"> <img src="rd_impression_url" style="width 1px; height 1px;"> </a> attributes description url string required “add to wallet” link url * see data transmit link * see data fetch link image_url string required button’s image resource url * see image resources rd_impression_url string required impressions logging url * value granted from the partners portal statistics service samsung wallet provides valuable statistical data related to the integrated services, accessible via the partners portal this data helps track key events, such as button impressions and user interactions, to optimize your service and improve the overall user experience note-statistics api sample code - the actual code sample is at the wallet script guide section in ‘wallet cards’ menu on the partner portal event notification api https //us-rd mcsvc samsung com/statistics/{event}/addtowlt?{parameters}&utm_source=partner&utm_medium={channel} {event} for each event in the following situations - impression when the “add to wallet” button has been shown - click when the “add to wallet” button has been clicked {parameters} includes key factors to figure out the service {channel} - app "samsung wallet" button in a native application - web "samsung wallet" button on the web - email "samsung wallet" button in an email for details, please visit 'wallet cards' menu on the partner portal