App Actions
Built-in outputs for driving conversions
Introduction
Actions can be referenced by your Javascript to invoke an action in the mobile app. This is where you will pair any business logic in your solution with a direct outcome in your users’ experience.
Using an App Action
In the Tapcart Text Editor
Actions will work out of the box as long as you are building inside of the Custom Blocks editor (In the Javascript tab). No further setup is required beyond using the proper syntax, and calling the function with the required parameters.
In a Custom Hosted Solution
Make sure you've already installed the relevant SDK, from there, they can be referenced as laid out here.
Testing Actions
App Actions do not return success/error states to the block upon being called. However, you can manually test actions via the block preview in the Custom Blocks text editor or in your own IDE's console. Actions will be printed to the browser console when successfully invoked.
Available App Actions
addToCart
addToCart
Use the addToCart
to support interactions that add 1 or more products to the cart. This action accepts an array of lineItems
, and additionally accepts custom line item attributes
. Attributes are helpful for passing custom data back to Shopify, and any other downstream systems as a result of an order. Note:If you use this App Action it will disable Apple Pay on the PDP if you have that feature turned on.
Tapcart.actions.addToCart({
lineItems: [
{
variantId: 'String',
quantity: Number,
sellingPlanId: 'String',
attributes: [ // optional
{
key: 'String',
value: 'String',
},
],
},
],
})
Navigating the user to checkout
Upon invoking the
addToCart
function, the app will reference this setting to determine if the user should be automatically navigated to the cart, or left where they are.
updateCartNote
updateCartNote
Use the updateCartNote
to update the note on the cart. These cart notes will be added once the cart is created (as soon as an item exists in the cart). The note will be removed once the cart has been ordered/completed
Dependencies for updateCartNote:
Custom Block Code Editor version: 1.7+
Tapcart.actions.updateCartNote({
note:'String'
})
Note: The cart only has one note. Updating the cart note will override any existing cart notes. Be sure to pull the current cart notes to see if you need to include it in the new cart note.
updateCartAttributes
updateCartAttributes
Use the updateCartAttributes
to update the attributes on the cart. This action passes key-value pairs that contains additional information about the cart. These cart attributes will be added once the cart is created (as soon as an item exists in the cart). They will be removed once the cart has been ordered/completed.
Dependencies for updateCartAttributes:
Custom Block Code Editor version: 1.7+
App must use Cart API
Tapcart.actions.updateCartAttributes({
attributes: [ // required
{
key: 'String (key1)',
value: 'String (value1)'
},
{
key: 'String (key2)',
value: 'String (value2)'
}
]
})
Note: Each attribute key is unique. If you apply multiple attributes with the same key, they will be overwritten. Updating the cart attributes will override any existing cart attributes. Be sure to pull the current cart attributes to see if you need to include it in the new cart attributes.
removeFromCart
removeFromCart
Use the removeFromCart
to support interactions that remove 1 or more products from the cart. This action accepts an array of lineItems
, and additionally accepts custom line item attributes
. Attributes are helpful for passing custom data back to Shopify, and any other downstream systems as a result of an order.
Note:If you use this App Action it will disable Apple Pay on the PDP if you have that feature turned on.
Dependencies for removeFromCart:
Custom Block Code Editor version: 1.5+
Tapcart.actions.removeFromCart({
lineItems: [
{
variantId: 'String',
quantity: Number,
sellingPlanId: 'String',
note: 'String',
attributes: [ // optional
{
key: 'String',
value: 'String',
},
],
},
],
})
openProduct
openProduct
Use the openProduct
to support interactions that take a user to a product detail page. This action accepts a productId
, and an optional variantId
if a specific variant needs to be pre-selecting upon opening the page. The isRelatedProduct
setting can be used if you are looking to relate different productIDs together into a single PDP. Setting isRelatedProduct
to true
will passively transition to new products from one PDP to another, setting it to false
will reload a new page when transferring to a new PDP (Available only on PDPs).
Tapcart.actions.openProduct({
productId: 'String',
variantId: 'String', // optional
isRelatedProduct: Boolean // optional, works only on PDPs
})
openCollection
openCollection
Use the openCollection
to support interactions that take a user to a product list page. This action accepts a collectionId
.
Tapcart.actions.openCollection({
collectionId: 'String',
})
openScreen
openScreen
Use the openScreen
to support interactions that take a user to a specific screen within the mobile app. This action accepts the type of screen, which will always be internal
if you are using a screen defined within the mobile app or web
if your are using a webview, while both types require a URL path for the screen. If using a web
type page URLs should be the full URL such as "https://www.example.com"
Tapcart.actions.openScreen({
destination: { type: "internal | web", url: "/some-known-url" }
})
Below are available screen URLs in app you can choose from. Additionally, you can call any custom screen you have added to the app using the method's below
Dependencies for openScreen:
Custom Block Code Editor version: 1.5+
Mobile App Screen Name | Type | URL |
---|---|---|
Account | internal | /account |
Cart | internal | /cart |
Collections | internal | /collections |
Home | internal | /home |
Orders | internal | /orders |
Mutli-page | internal | /home?tabIndex=1 |
Notifications | internal | /notifications |
Wishlist | internal | /wishlist |
Loyalty | internal | /loyalty |
Subscriptions | internal | /subscriptions |
Custom Screen - Web-based | internal | /hybrid-pages/:id |
Custom Screen- Block-based | internal | /blocks-page/:id |
Webview | web | https://www.tapcart.com/ |
Note
If you're linking a Custom Screen, the Screen ID can be found on the custom screen settings panel under the Screen Title (see image below)
getCustomerIdentity
getCustomerIdentity
Use the getCustomerIdentity
to request the email address of a user who is signed into the app. This action is asynchronous and accepts an onSuccess
callback function will fire when it completes. The customer data will be passed as a parameter to your callback function.
Dependencies for getCustomerIdentity:
Custom Block Code Editor version: 1.5+
Tapcart.actions.getCustomerIdentity(null, {
onSuccess: (res) => {
console.log("getCustomerIdentity success", res);
}
})
"customer": {
"email": "[email protected]",
"firstName": "John",
"shopifyId": "1234"
},
applyDiscount
applyDiscount
Use the applyDiscount
to allow a solution to apply a discount to a user's cart. This action accepts a discountCode
. To use this action, the cart will need at least 1 product in it, so make sure to add a product to the cart before invoking this action. When calling this action, the discount won't be applied until the user visits the cart, this allows you to manage the applied discounts using a combination of removeDiscounts
& applyDiscount
leading up to the user's arrival at the cart.
Tapcart.actions.applyDiscount({
discountCode: 'String',
})
removeDiscounts
removeDiscounts
Use the removeDiscounts
to clear a user's cart of any applied discounts. This action does not accept any parameters, and will remove all discounts that are currently applied to the cart, or in queue to be applied to the cart from the applyDiscount
action. If you want to selectively remove discounts, you should first clear the cart of discounts, and reapply discounts as needed using applyDiscount
. You can leverage the Tapcart.variables.cart.appliedDiscounts
variable to parse any applied discounts before calling removeDiscount
.
Tapcart.actions.removeDiscounts()
showToast
showToast
Use the showToast
to display success or error messages to your end users. This will display natively & will be presented at the top of the page. This action accepts a a message
, and a type
to denote if it's a success or error message.
Tapcart.actions.showToast({
message: 'String',
type: 'String', // "success" || "error"
})
scrollToBlockTop
// scrollToBlockBottom
scrollToBlockTop
// scrollToBlockBottom
Use the scrollToBlockTop
or scrollToBlockBottom
to scroll to the top or bottom of a block you've built when needed.
Custom Block Code Editor version: 1.6+
Tapcart.actions.scrollToBlockTop()
Tapcart.actions.scrollToBlockBottom()
Updated 7 days ago