# Account Page (/docs/build/account-and-login/account-page) ### Page ID [#page-id] The page ID for the Account page is **`MyAccount`**. Use this when registering a replacement page in `pages/index.js`. ```js import AccountPage from './account'; const pages = { MyAccount: AccountPage, }; export { pages }; ``` ### Basic page structure [#basic-page-structure] ```js const MyAccount = { title: 'My Account', attributes: { renderType: 'normal', renderInScroll: true, backgroundColor: '#FFFFFF', scrollViewContentContainerStyle: { paddingHorizontal: 6, paddingTop: 8, }, }, blocks: [ { name: 'appmaker/shopify-access-token-checker', attributes: { user: '{{appStorageState.user}}', }, }, { name: 'shopify/profile-card-item', attributes: {}, }, { clientId: 'my-account-menu-orders', name: 'appmaker/actionbar', attributes: { title: 'Orders', appmakerAction: { pageId: 'OrderList', params: { pageData: '{{appStorageState.user}}', }, action: 'OPEN_INAPP_PAGE', }, }, dependencies: { appStorageState: ['user'], }, }, { clientId: 'address-list', name: 'appmaker/actionbar', attributes: { title: 'Address', __display: '{{!checkIfTrueFalse(plugins.shopify.settings.hide_myaccount_address)}}', appmakerAction: { params: {}, action: 'OPEN_ADDRESS_LIST_PAGE', }, }, }, { clientId: 'my-account-menu', name: 'appmaker/actionbar', attributes: { title: 'Delete account', __display: '{{__platformOS === "ios" }}', appmakerAction: { params: {}, action: 'OPEN_INAPP_PAGE', pageId: 'DeleteAccountConfirmation', }, }, }, { clientId: 'my-account-menu', name: 'appmaker/actionbar', attributes: { title: 'Log out', appmakerAction: { params: {}, action: 'LOGOUT', }, }, }, ], }; export default MyAccount; ``` ### Basic Blocks [#basic-blocks] #### 1. appmaker/shopify-access-token-checker [#1-appmakershopify-access-token-checker] Validates the user's session. Redirects to the login page if the user is not authenticated. #### 2. shopify/profile-card-item [#2-shopifyprofile-card-item] Displays the user's profile avatar, name and email. #### 3. appmaker/actionbar [#3-appmakeractionbar] A reusable list item block used to create navigation entries. Each entry has a `title` and an optional `appmakerAction`. | Entry | Action | Notes | |---|---|---| | Orders | Opens `OrderList` page | | | Address | Triggers `OPEN_ADDRESS_LIST_PAGE` | Conditionally shown based on `hide_myaccount_address` setting | | Delete account | Opens `DeleteAccountConfirmation` page | iOS only | | Log out | Triggers `LOGOUT` | | ### Customization [#customization] Block customization can be done by overriding the block. #### Eg: Customizing the profile card [#eg-customizing-the-profile-card] Customize the user profile card by overriding the `shopify/profile-card-item` block. Create a new component in the `./components` folder and register it to the block registry in `./blocks/index.js` with the same block name. ```js { name: 'shopify/profile-card-item', attributes: {}, } ``` # How to create custom OTP login (/docs/build/account-and-login/custom-otp-extension) ## `appmaker-send-phone-otp` [#appmaker-send-phone-otp] This filter is used to send OTP to the user's phone number. | Parameter | Type | Description | | :--- | :--- | :--- | | phone | String | The phone number of the user. | #### Usage [#usage] ```js export const productResponse = () => { appmaker.addFilter( 'appmaker-send-phone-otp', 'custom-otp', async ({ phone }) => { const data = await requestOtp({ // Your custom processing logic goes here username: phone, type, }); return { data: data, }; }, ); }; ``` ## `appmaker-re-send-phone-otp` [#appmaker-re-send-phone-otp] This filter is used to re-send OTP to the user's phone number. | Parameter | Type | Description | | :--- | :--- | :--- | | phone | String | The phone number of the user. | #### Usage [#usage-1] ```js export const productResponse = () => { appmaker.addFilter( 'appmaker-re-send-phone-otp', 'custom-otp', async ({ phone }) => { const data = await resendOtp({ // Your custom processing logic goes here username: phone, type, }); return { data: data, }; }, ); }; ``` ## `appmaker-verify-phone-otp` [#appmaker-verify-phone-otp] This filter is used to verify the OTP sent to the user's phone number. | Parameter | Type | Description | | :--- | :--- | :--- | | phone | String | The phone number of the user. | | otpCode | String | The OTP code entered by the user. | | otpResponse | Object | The response received from the server after sending the OTP. | | redirectAction | Object | The redirect action to be performed after the OTP is verified. | #### Usage [#usage-2] ```js export const productResponse = () => { appmaker.addFilter( 'appmaker-verify-phone-otp', 'custom-otp', async ({ phone, otpCode, otpResponse, redirectAction }) => { const responseData = await verifyOtp({ // Your custom processing logic goes here username: phone, otp: otpCode, otp_id: otpResponse?.data?.otpId, type, }); if (responseData?.status === 200) { const multipass_url = responseData.data.multipass_url; // await processLogin({}); let multipassToken; if (multipass_url) { multipassToken = multipass_url.match(/multipass\/(.*)/)[1]; } return { status: 'success', nextStep: multipassToken ? 'done' : 'custom_action', // If multipassToken is present, the user is logged in successfully, else the user is redirected to the AccountDetails page. customAction: { action: 'OPEN_INAPP_PAGE', pageId: 'AccountDetails', params: { redirectAction, pageData: { redirectAction, // phone otpId: otpResponse?.data?.otpId, email: '', email_disabled: false, phone_disabled: true, phone, first_name: responseData?.data?.firstName || '', last_name: responseData?.data?.lastName || '', }, }, }, multipassToken, userCredentials: {}, data: responseData, }; } else { return { status: 'fail', error: responseData, }; } }, ); }; ``` ## `appmaker-submit-account-details` [#appmaker-submit-account-details] This filter is used to submit the account details of the user. | Parameter | Type | Description | | :--- | :--- | :--- | | onAction | Function | The function to be called when the action is performed. | | attrs | Object | The attributes of the user. | #### Usage [#usage-3] ```js export const productResponse = () => { appmaker.addFilter( 'appmaker-submit-account-details', 'custom-otp', async ({ onAction, ...attrs }) => { return response; }, ); }; ``` # Google Login for Android/iOS (/docs/build/account-and-login/google-login-for-android-ios) ## Overview [#overview] This doc will help you to integrate google login in your android and iOS app. ## Prerequisites [#prerequisites] 1. You must have Push notification configured through appmaker dashboard. 2. You must have enabled Multipass login in shopify store, and get the Multipass secret key from shopify store. 3. Enable **Shopify Multipass** extension in appmaker dashboard, and add the Multipass secret key in the extension Admin settings. ## Steps [#steps] 1. Make sure you have activated **Google login** extension in your appmaker dashboard 2. Go to the Firebase dashboard, click Project Overview 3. Select Project Settings, the settings page appears 4. Scroll down and click on the Add fingerprint for Android apps 5. Add the below SHA-1 key as a fingerprint ``` ed:34:3a:18:65:11:42:b5:44:7f:0d:c3:41:67:08:68:ab:9a:05:dc ``` 6. Next, go to Authentication and click Get Started 7. Click on Google to edit and enable the button 8. Enter your app name without space in the Project public-facing name field 9. Enter email id in the Project support email field and click Save to complete the process To test the Google login in the app, download the latest apk version from your Appmaker dashboard and test the app. The Google login feature will now work for both Android and iOS devices. You can now publish the app or release an updated version of the app in the Apple app store and Google Play Store. The app will now work properly with the Google login feature on iOS devices. However, for Android, there is an additional step that needs to be implemented after the app is published in Google Play Store. ## Additional step after you release the app to Google Play Store [#additional-step-after-you-release-the-app-to-google-play-store] After you release the app to Google Play Store, you need to add the SHA-1 key of the Google Play Store to the Firebase console. This is required to make the Google login feature work on Android devices. 1. Publish the app in Google Play Store 2. Once the app is published, go to your [Google Play Console](https://play.google.com/console/about/) 3. Click Release management and select App signing, the App signing page appears 4. Go to App signing certificate and copy the text after SHA1 from the SHA-1 certificate fingerprint Do not include the text SHA1 while copying 5. Go to [Firebase](https://firebase.google.com/) 6. Click on Project Overview and select Project Settings 7. Scroll down and click on Add Fingerprint for Android apps 8. Paste the SHA1 text in the box under the SHA certificate fingerprints to complete the process You are good to go now! Users can now login to your app using this easy-to-go Google login feature. # How to add delete account tab (/docs/build/account-and-login/how-to-add-delete-account-tab) This tutorial will guide you through the steps of adding a delete account tab to your app on theme. ### Solution 1: Add alert on your custom delete account button [#solution-1-add-alert-on-your-custom-delete-account-button] If you have your own custom delete account button on theme, you can add an alert to it. The button should only be visible on iOS and should trigger a confirmation alert when pressed. ```jsx import { Alert } from 'react-native'; Alert.alert( 'Delete Account', 'Are you sure you want to delete your account? ', [ { text: 'Cancel', style: 'cancel', }, { text: 'Delete', onPress: () => onAction({ action: 'DELETE_ACCOUNT' }), style: 'destructive', }, ], { cancelable: true } ); ``` ### Solution 2: use default delete account tab [#solution-2-use-default-delete-account-tab] You can use the default delete account tab. To do this, you need to add the following tab item to your myAccount page ```jsx { name: 'appmaker/ActionButton', clientId: 'delete-account-confirmation-button-yes', attributes: { appmakerAction: { action: 'DELETE_ACCOUNT', }, content: 'Delete account anyway', baseSize: true, wholeContainerStyle: { backgroundColor: '#FECACA', }, fontColor: '#B91C1C', }, contextValues: true, }, ``` # How to create a apple login button (/docs/build/account-and-login/how-to-create-apple-login-button) ## Steps [#steps] 1. Make sure to activate apple login extension from Appmaker Dashboard, and configure it correctly. 2. Make a block for the apple login component Example: ```js { name: 'your-theme/apple-login-button', clientId: 'your-theme-apple-Login', attributes: {}, } ``` 3. Register the block in your theme Example: ```js import AppleLoginComponent from './components/AppleLoginComponent'; name: 'your-theme/apple-login-button', View: AppleLoginComponent, ``` 4. Make a component for the apple login button ```js import { Button, Text } from 'react-native'; import React, { useEffect, useState } from 'react'; import { usePageState } from '@appmaker-xyz/core'; export default function AppleLoginComponent({ attributes, onAction }) { const appleLoginLoading = usePageState((state) => state.appleLoginLoading); const [buttonLoading, setButtonLoading] = useState(false); useEffect(() => { setButtonLoading(appleLoginLoading); }, [appleLoginLoading]); if (buttonLoading) { return ( Loading... ); } return ( )} ); } ``` - In this example, the usePageState hook is used to retrieve the current value of the modalVisible state and the setPageState function. - The modal is conditionally rendered based on the value of modalVisible, and the setPageState function is used to toggle the visibility of the modal when the "Open" and "Close" buttons are pressed. # How to use runDataSource function to run a gqlQuery function (/docs/build/data/how-to-use-rundatasource) ## Description [#description] This document describes how to use `runDataSource` function to run `gqlQuery` method of `dataSource` object. This is for developers who want to use custom graphql queries to fetch data from `shopify dataSource`. ## Steps [#steps] 1. Import `runDataSource` function from `@appmaker-xyz/core` package. ```js import { runDataSource } from "@appmaker-xyz/core"; ``` 2. Create dataSource object with `attributes` and `source` properties. ```js const dataSource = { attributes: {}, source: "shopify", }; ``` 3. Call `runDataSource` function with `dataSource` object and `methodName` as `gqlQuery` and `params` properties. ```js const [response] = await runDataSource( { dataSource, }, { methodName: "gqlQuery", params: { query: ` query getMediaImages($ids: [ID!]!) { nodes(ids: $ids) { ... on MediaImage { alt id image { url(transform:{maxHeight: 800, maxWidth: 800}) } } } } `, variables: { "ids": [ "gid://shopify/MediaImage/27773354672290", "gid://shopify/MediaImage/27569974116510", "gid://shopify/MediaImage/27505126113438" ] } }, } ); console.log(response); ``` 4. You will get the response as below. ```js { "data": { "nodes": [ { "alt": "alt text", "id": "gid://shopify/MediaImage/27773354672290", "image": { "url": "https://cdn.shopify.com/s/files/1/0006/9093/3842/files/1_800x.jpg?v=1588080000" } }, { "alt": "alt text", "id": "gid://shopify/MediaImage/27569974116510", "image": { "url": "https://cdn.shopify.com/s/files/1/0006/9093/3842/files/2_800x.jpg?v=1588080000" } }, { "alt": "alt text", "id": "gid://shopify/MediaImage/27505126113438", "image": { "url": "https://cdn.shopify.com/s/files/1/0006/9093/3842/files/3_800x.jpg?v=1588080000" } } ] } } ``` # Data & queries (/docs/build/data) # How to query metafields via GraphQL (/docs/build/data/metafields-in-page-data) ## Introduction [#introduction] This guide will help you fetch your collection or product metafield data using GraphQL instead of filters. ## Query [#query] You need to first write a query to fetch the metafield data. Below is an example query to fetch the metafield data. ```graphql query GetProductDetails($handle: String) { collection(handle: $handle) { custom_field_1: metafield(key: "field_key_1", namespace: "field_namespace_1") { __typename value } custom_field_1: metafield(key: "field_key_2", namespace: "field_namespace_2") { __typename value } } } ``` Let's break down the query: - `collection(handle: $handle)`: This is the collection query. You can replace `collection` with `product` if you want to fetch product metafield data. - `custom_field_1: metafield(key: "field_key_1", namespace: "field_namespace_1")`: This is the metafield query. You can replace `custom_field_1` with any name you want. This name would be used as a key for this metafield in the query response. `field_key_1` is the key of the metafield and `field_namespace_1` is the namespace of the metafield. ## Usage [#usage] You can use the above query to fetch the metafield data. Below is an example of how you can use the query to fetch the metafield data. ```js const query = `#graphql query GetProductDetails($handle: String) { collection(handle: $handle) { custom_field_1: metafield(key: "field_key_1", namespace: "field_namespace_1") { __typename value } custom_field_1: metafield(key: "field_key_2", namespace: "field_namespace_2") { __typename value } } } ` const productList = { title: 'Product list', attributes: { insideSafeAreaView: true, headerShown: true, }, blocks: [ { name: 'shopify/page-meta-graphql-query', attributes: { pageStateName: 'collection-meta', query: query, variables: { handle: '{{blockData.collection.handle}}', }, }, }, { attributes: {}, name: 'appmaker/shopify-product-list', innerBlocks: [], clientId: 'product-list', isValid: true, }, ] } export default productList; ``` The above code will fetch the metafield data and make it available throughout the page for all blocks within it. You can add the query and the `shopify/page-meta-graphql-query` block to any page where you want to fetch the metafield data. Note: `collection-meta` is the name of the metadata state where the metafield data will be stored. ## Accessing the metafield data [#accessing-the-metafield-data] You can now access the metafield data in your blocks using the `usePageMetaDataState` method. Below is an example of how you can access the metafield data in your blocks. ```js import React from 'react'; import { ThemeText, Layout } from "@appmaker-xyz/ui"; import { usePageMetaDataState } from "@appmaker-xyz/core"; const ProductList = () => { const { data } = usePageMetaDataState("collection-meta"); const metafield1 = data?.collection?.custom_field_1?.value; const metafield2 = data?.collection?.custom_field_2?.value; return ( {metafield1} {metafield2} ); }; ``` Make sure to parse the result of the value in the metafield if you're expect objects or arrays. # Build your app (/docs/build) # Page Background Image (/docs/build/look-and-feel/background-image) The image will be displayed behind the page content. ## Usage [#usage] To set a background image for a page, you need to add a `pageBackgroundImageSrc` or `pageBackgroundImageUri` to the page's attributes. Priority is given to `pageBackgroundImageSrc` over `pageBackgroundImageUri`. ### Example [#example] ```jsx const Page={ type:'normal', title:'Page with background image', attributes:{ pageBackgroundImageSrc:require('./image.jpg') // or pageBackgroundImageUri:'https://example.com/image.jpg' // ... other attributes }, // ... other page properties and blocks } ``` > Note: Make sure `rootContainerStyle` and `contentContainerStyle` are not setting `backgroundColor` or `opacity` to avoid conflicts with the background image. ## Feature related attributes [#feature-related-attributes] | Attribute | Type | Description | Example | | --------- | ---- | ----------- | ------- | | `pageBackgroundImageSrc` | Object | The source of the background image. | `require("./image.jpg")` | | `pageBackgroundImageUri` | String | The URI of the background image. | `https://example.com/image.jpg` | | `pageBackgroundImageResizeMode` | String | The resize mode of the background image. | `cover` | | `pageBackgroundImageStyle` | Object | The style of the background image. | `{ opacity: 0.5 }` | |`pageBackgroundContainerStyle`| Object | The style of the background container. | `{ flex: 1 }` | ### Example using `inapp-page-data-response` filter [#example-using-inapp-page-data-response-filter] ```js appmaker.addFilter( 'inapp-page-data-response', 'theme-luxe-avenue', (data, { pageId }) => { if (pageId == 'LoginOptions') { // Update page background image URI data.attributes.pageBackgroundImageUri = 'https://cdn.shopify.com/s/files/1/0734/8643/4599/products/2014_10_18_Lana_Look1101.jpg?v=1680513077'; // Remove backgroundColor if present in rootContainerStyle if ( data.attributes.rootContainerStyle && data.attributes.rootContainerStyle.backgroundColor ) { delete data.attributes.rootContainerStyle.backgroundColor; } // Remove backgroundColor if present in contentContainerStyle if ( data.attributes.contentContainerStyle && data.attributes.contentContainerStyle.backgroundColor ) { delete data.attributes.contentContainerStyle.backgroundColor; } } return data; }, ); ``` # How to Customise the Appmaker Message View (/docs/build/look-and-feel/custom-message-view) ## Description [#description] In this doc we will see how to customise the Appmaker message view using `react-native-toast-notifications`. We will be using the `react-native-toast-notifications` library to customise the message view. By this method we can conditionally show the message view based on the message type. ## Steps [#steps] 1. Add `react-native-toast-notifications` library to your theme peer dependencies. 2. For this library to work you have to add a wrapper for your app code. For this you can add the following code in your theme `index.js` file. ```js import { Toast } from 'react-native-toast-notifications'; import { addFilter } from '@appmaker-xyz/core'; function activate(settings) { addFilter('wrap-appmaker-app-component', 'your-theme', (App) => { const FinalApp = (props) => ( ); return FinalApp; }); } ``` 3. In your theme `index.js` inside the `activate` function add the following code. ```js import { Toast } from 'react-native-toast-notifications'; import { addFilter } from '@appmaker-xyz/core'; function activate(settings) { addFilter('change-appmaker-message-view-success','your-theme', (currentValue,{ title, buttonTitle, buttonAction, message }, deps,) => { if(title == 'Added to cart') { Toast.show(title, { type: 'success', placement: 'bottom', duration: 4000, offset: 30, animationType: 'slide-in', }); return true; // return true to hide default appmaker message view } return currentValue; // return currentValue to show default appmaker message view }); } ``` 4. For customizing the message view for different message types you can you can refer to the `react-native-toast-notifications` library [documentation](https://github.com/arnnis/react-native-toast-notifications#custom-toast-types). You can refer to their docs for more customizations. # Customize Font (/docs/build/look-and-feel/customize-font) The following sections describe how to customize the font. In-order to change the font in the other areas of the app were the font is not controlled by the theme, you can use the custom fonts extension. Refer [this](https://docs.appmaker.xyz/docs/Extensions/custom-font) for more details. ## Preparing Font Files [#preparing-font-files] 1. **Font Files:** Obtain the required font files from your font provider. 2. **File Format:** Ensure that the font files are in `.ttf` format. The file extension is case-sensitive and should be in lowercase. 3. **Font Name Consistency:** The font file name must match the font's full name. Verify this by checking the font information on your system. If the names do not match, rename the font file accordingly. 4. **Using [Font Renamer](https://font-renamer.vercel.app):** - **Upload:** Upload the font files to [font-renamer](https://font-renamer.vercel.app). This tool renames the files based on their internal names. - **Download:** Retrieve the renamed font files either individually or as a zip file. - **Utilize:** Use these renamed font files in your theme. - **Update Theme Configuration:** Font Renamer also generates a JSON mapping to prevent font name conflicts in React Native builds. If using renamed font files, update the `appmaker-theme.json` file with the JSON provided by Font Renamer. Adjust key names to `regular`, `medium`, `bold` as needed. ## Adding Custom Fonts to the Theme [#adding-custom-fonts-to-the-theme] 1. **Create Fonts Directory:** Create a `fonts` folder within the `src/assets` directory. 2. **Add Font Files:** Place your font files into the newly created `fonts` folder. ```bash ├── src │ ├── assets │ ├── fonts │ ├── SF-Pro-Display-Regular.ttf │ ├── SF-Pro-Display-Medium.ttf │ └── SF-Pro-Display-Bold.ttf └── appmaker-theme.json ``` 3. **Update Configuration:** Create or update the `appmaker-theme.json` file in the root folder with the relevant font details. ```json title="src/appmaker-theme.json" { "fontFamily": { "regular": "SF-Pro-Display-Regular", "medium": "SF-Pro-Display-Medium", "bold": "SF-Pro-Display-Bold" } } ``` The font name should match the font file name without the extension. ## Using the `ThemeText` Component [#using-the-themetext-component] The `ThemeText` component is a custom text component that leverages the theme's font family. Use this component instead of the default `Text` component to ensure the theme's font is applied. Regular, medium, and bold names defined in [custom font](https://docs.appmaker.xyz/docs/Extensions/custom-font/) extension are used to apply the font family. Example: ```jsx title="SampleComponent.js" import { ThemeText } from "@appmaker-xyz/ui"; const SampleComponent = () => { return ( Custom Font ); }; export default SampleComponent; ``` ### `ThemeText` Props [#themetext-props] #### [Text props](https://reactnative.dev/docs/text#props) [#text-props] The `ThemeText` component inherits all the props from the `Text` component. Additionally, it offers the following props: | Prop | Type | Default | Description | | ---------------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `style` | object | `{}` | Style object to apply additional styles to the text component. | | `children` | node | | Text content to display. | | `size` | string | `base` | Font size variant.
Possible values: `xs`, `10`, `sm`, `base`,`md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`. | | `fontFamily` | string | `regular` | Font weight variant.
Possible values: `regular`, `medium`, `bold`.
This apply font names you have added in [custom-font](https://docs.appmaker.xyz/docs/Extensions/custom-font/) extension or default font family. | | `color` | string | '#000000' | Text color. | | `striptags` | bool | `false` | Strip HTML tags from the text content. | | `hideText` | bool | `false` | Conditionally hide the text content. | | `html` | bool | `false` | Render text content as HTML.
**Note**: The above properties may not work if this is enabled. | | `customHtmlTagsStyles` | object | `{}` | Custom styles for HTML tags.
Format: `{ tag: { style: { key: value } } }` | Size guide for `size` prop: | Size | Value | | ---- | ----- | | xs | 8 | | 10 | 10 | | sm | 12 | | base | 14 | | md | 16 | | lg | 18 | | xl | 24 | | 2xl | 28 | | 3xl | 32 | | 4xl | 36 | ## Using additional fonts families other than regular, medium, and bold [#using-additional-fonts-families-other-than-regular-medium-and-bold] Add and use custom fonts in your project by placing font files in the `src/assets/fonts` directory, updating the `appmaker-theme.json` file, defining the fonts in `src/styles/index.js`, and applying them using the `ThemeText` or `Text` component with `styles` as shown below.
Additional Fonts (Steps) 1. To use a font other than regular, medium, and bold, you can follow above steps and add as many fonts as per your requirement to the `src/assets/fonts` directory. Then, update the `appmaker-theme.json` file with the new font family. ```json title="src/appmaker-theme.json" { "fontFamily": { "regular": "SF-Pro-Display-Regular", "medium": "SF-Pro-Display-Medium", "bold": "SF-Pro-Display-Bold", "custom": "Custom-Font" // Add the custom font. This is for app build purpose } } ``` 2. Create a styles index file to define the custom font family in `src/styles/index.js`. ```js title="src/styles/index.js" const additionalFonts = { custom: "Custom-Font", // Add the custom font. Use this for styling }; export { additionalFonts }; ``` 3. Now, you can use the `ThemeText` or `Text` component to apply the custom font in the styles. ```jsx title="SampleComponent.js" import { ThemeText } from "@appmaker-xyz/ui"; import { StyleSheet } from "react-native"; import { additionalFonts } from "../styles"; // Import the styles index file const SampleComponent = () => { return ( Custom Font ); }; const styles = StyleSheet.create({ text: { fontFamily: additionalFonts.custom, // Apply the custom font }, }); export default SampleComponent; ```
You can apply a custom `fontSize` using the `style` prop. The `size` prop is specifically for predefined font sizes. Using a custom `fontWeight` in the `style` prop will override the `fontFamily` prop. Therefore, it is recommended to avoid setting `fontWeight` in the `style` prop. # How to customize your app's splashscreen (/docs/build/look-and-feel/how-to-customize-splashscreen) ## Overview [#overview] This tutorial shows you how to customize the SplashScreen component. You can control splash behavior in three ways: 1. **Timeout based** — show the splash for a fixed duration 2. **Wait handler based** — wait for an API call or async work before proceeding 3. **Custom component** — replace the splash screen UI All filters must be registered **outside the activate function** of your theme. Otherwise, the filters won't be applied before the SplashScreen is shown. This flow is used only when custom splash is enabled through `app-settings.enable_custom_splash`. ## Resolution order [#resolution-order] When the splash screen mounts, it resolves what to wait for in this order: 1. `appmaker-splash-screen-wait-handler` — if registered, takes full control 2. `appmaker-splash-screen-timeout` — if registered, overrides the default timeout 3. `splash_screen_timeout` from app settings — the default fallback ## Timeout based splash [#timeout-based-splash] Use `appmaker-splash-screen-timeout` when you only want a fixed delay. ```js import { appmaker } from "@appmaker-xyz/core"; // Change the timeout. Default is from app settings (typically 500 ms). appmaker.addFilter( "appmaker-splash-screen-timeout", "my-theme-name", () => 5000 // timeout in ms ); ``` ## Wait for an API before loading the app [#wait-for-an-api-before-loading-the-app] Use `appmaker-splash-screen-wait-handler` when the splash should wait for custom async work like an API call before the app loads. The handler receives a context object with: - `timeout` — the resolved timeout from `appmaker-splash-screen-timeout` or app settings - `waitForTimeout(timeout?)` — helper that returns a promise resolving after the given timeout ### Wait only for API completion [#wait-only-for-api-completion] For production use, consider adding an AbortSignal tied to the timeout value to avoid indefinite waits. See the fallback example below. ```js import { appmaker } from "@appmaker-xyz/core"; appmaker.addFilter( "appmaker-splash-screen-wait-handler", "my-theme/splash-api-wait", () => async () => { const response = await fetch("https://example.com/bootstrap"); await response.json(); } ); ``` ### Wait for API or fall back to timeout [#wait-for-api-or-fall-back-to-timeout] ```js import { appmaker } from "@appmaker-xyz/core"; appmaker.addFilter( "appmaker-splash-screen-timeout", "my-theme/splash-timeout", () => 5000 ); appmaker.addFilter( "appmaker-splash-screen-wait-handler", "my-theme/splash-api-wait", () => async ({ timeout, waitForTimeout }) => { const controller = new AbortController(); const fallbackTimer = setTimeout(() => controller.abort(), timeout); try { const response = await fetch("https://example.com/bootstrap", { signal: controller.signal, }); await response.json(); } catch (error) { // If the API call fails or times out, the app continues loading return; } finally { clearTimeout(fallbackTimer); } } ); ``` ### Reuse the old timeout through the new filter [#reuse-the-old-timeout-through-the-new-filter] ```js import { appmaker } from "@appmaker-xyz/core"; appmaker.addFilter( "appmaker-splash-screen-wait-handler", "my-theme/splash-wait-handler", () => ({ timeout, waitForTimeout }) => waitForTimeout(timeout) ); ``` ### Supported return types [#supported-return-types] The `appmaker-splash-screen-wait-handler` filter can return: | Return type | Behavior | |---|---| | Function | Called with `{ timeout, waitForTimeout }` context, result is processed recursively | | Promise | Awaited before proceeding | | Number | Used as a timeout in milliseconds | | Numeric string (e.g. `"3000"`) | Parsed and used as a timeout | | `null`, `undefined`, or `void` | Falls back to the default timeout | ### Error handling [#error-handling] If the wait handler throws or rejects, the app logs the error and continues loading. The splash screen will never get stuck. ## Custom splash component [#custom-splash-component] Use `appmaker-splash-screen-component` to replace the splash screen UI. ```js import { appmaker } from "@appmaker-xyz/core"; import SplashScreen from "./SplashScreen"; appmaker.addFilter( "appmaker-splash-screen-component", "my-theme-name", () => SplashScreen ); function activate(theme) { // your theme activate function codes } ``` ### Example: Video splash screen [#example-video-splash-screen] ```js import React from "react"; import { View } from "react-native"; import Video from "react-native-video"; const SplashScreen = () => { return ( ); }; export default SplashScreen; ``` ## Full example [#full-example] Combining all three filters — custom timeout, async wait handler, and custom component: ```js import { appmaker } from "@appmaker-xyz/core"; import SplashScreen from "./SplashScreen"; // 1. Set a custom timeout (used as fallback) appmaker.addFilter( "appmaker-splash-screen-timeout", "my-theme-name", () => 5000 ); // 2. Wait for bootstrap API before loading appmaker.addFilter( "appmaker-splash-screen-wait-handler", "my-theme-name", () => async ({ timeout }) => { const controller = new AbortController(); const fallbackTimer = setTimeout(() => controller.abort(), timeout); try { const response = await fetch("https://example.com/bootstrap", { signal: controller.signal, }); await response.json(); } catch (error) { return; } finally { clearTimeout(fallbackTimer); } } ); // 3. Use a custom splash component appmaker.addFilter( "appmaker-splash-screen-component", "my-theme-name", () => SplashScreen ); function activate(theme) { // your theme activate function codes } ``` # How to remove scrollbar from page (/docs/build/look-and-feel/how-to-remove-scrollbar) ```js attributes: { headerShown: false, showsVerticalScrollIndicator: false, // Add this attribute rootContainerStyle: { flex: 1, }, contentContainerStyle: { flex: 1, }, }, ``` # How to use SafeArea Context for iOS devices in Component level (/docs/build/look-and-feel/how-to-use-safeareacontext-for-ios) ## Description [#description] In iOS devices to use safe are padding you can use with safe area context library. ## Usage [#usage] ```js import { useSafeArea } from "react-native-safe-area-context"; const MyComponent = () => { const insets = useSafeArea(); return ( {/* Code here */} ); }; ``` # Look & feel (/docs/build/look-and-feel) # Right-to-Left (RTL) Styling Best Practices (/docs/build/look-and-feel/rtl-best-practices) In RTL languages, the text is written from right to left. When designing an app for RTL languages, it is important to consider the following best practices: ### Styling Components for RTL and LTR Layouts [#styling-components-for-rtl-and-ltr-layouts] Certain UI elements need to be mirrored when switching between RTL and LTR. To handle this: #### Direction-Aware Flexbox Layouts [#direction-aware-flexbox-layouts] Flexbox automatically handles direction-based layouts, but you should be mindful of `flexDirection`, `alignItems`, and `justifyContent` properties. For example: ```jsx const styles = StyleSheet.create({ container: { flexDirection: I18nManager.isRTL ? "row-reverse" : "row", }, }); ``` #### Padding and Margin Adjustments [#padding-and-margin-adjustments] While setting padding and margin, use directional properties such as `paddingStart`, `paddingEnd`, `marginStart`, and `marginEnd` instead of absolute values like `paddingLeft` and `paddingRight`. ```jsx const styles = StyleSheet.create({ container: { paddingStart: 10, // Automatically adjusts for RTL paddingEnd: 10, }, }); ``` #### Text Alignment [#text-alignment] For text alignment, use `textAlign: 'auto'` which automatically handles alignment based on the language direction. Alternatively: ```jsx textAlign: I18nManager.isRTL ? "right" : "left"; ``` #### TextInput Component [#textinput-component] For `TextInput`, RTL text should automatically be supported. However, you may need to handle placeholders and input text alignment: ```jsx ``` Also, consider setting `textAlignVertical` if the input spans multiple lines. #### Horizontal Scrolling in RTL Mode [#horizontal-scrolling-in-rtl-mode] - By default, when `FlatList` is used with horizontal scrolling (`horizontal={true}`) and the app is in RTL mode, the list automatically starts from the right. - The content will align accordingly, and the list scrolls from right to left, which is the expected behavior for RTL layouts. - **Inverting the Scroll Behavior:** ```jsx ``` Below is a detailed table of RTL-supported style properties in React Native. These properties automatically adjust their behavior based on the layout direction (LTR or RTL). #### Icons and Images [#icons-and-images] When using icons and images, ensure that they are mirrored correctly for RTL layouts. Some icons and images might need to be mirrored in RTL mode. React Native supports this with the `transform` property: ```jsx ``` ### Table of RTL-Supported Styles [#table-of-rtl-supported-styles] | Style Property | Description | Equivalent LTR Property | Equivalent RTL Property | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------------- | | **`paddingStart`** | Sets padding at the leading edge (start) of the container. Adjusts based on layout direction (LTR/RTL). | `paddingLeft` | `paddingRight` | | **`paddingEnd`** | Sets padding at the trailing edge (end) of the container. Adjusts based on layout direction (LTR/RTL). | `paddingRight` | `paddingLeft` | | **`marginStart`** | Sets margin at the leading edge (start) of the container. Adjusts based on layout direction (LTR/RTL). | `marginLeft` | `marginRight` | | **`marginEnd`** | Sets margin at the trailing edge (end) of the container. Adjusts based on layout direction (LTR/RTL). | `marginRight` | `marginLeft` | | **`start`** | Sets position from the leading edge (start) for absolute/relative positioning. Adjusts based on layout direction (LTR/RTL). | `left` | `right` | | **`end`** | Sets position from the trailing edge (end) for absolute/relative positioning. Adjusts based on layout direction (LTR/RTL). | `right` | `left` | | **`textAlign`** | Adjusts text alignment based on the layout direction. Use `'auto'` for automatic alignment based on LTR/RTL. | `left`, `center`, `right` | Same as LTR | | **`flexDirection`** | Defines the primary axis of layout. Use `'row-reverse'` for RTL-specific adjustments. | `row`, `column` | `row-reverse`, `column` | | **`borderStartWidth`** | Sets border width at the leading edge (start) of the container. Adjusts based on layout direction (LTR/RTL). | `borderLeftWidth` | `borderRightWidth` | | **`borderEndWidth`** | Sets border width at the trailing edge (end) of the container. Adjusts based on layout direction (LTR/RTL). | `borderRightWidth` | `borderLeftWidth` | | **`borderStartColor`** | Sets border color at the leading edge (start) of the container. Adjusts based on layout direction (LTR/RTL). | `borderLeftColor` | `borderRightColor` | | **`borderEndColor`** | Sets border color at the trailing edge (end) of the container. Adjusts based on layout direction (LTR/RTL). | `borderRightColor` | `borderLeftColor` | ### Key Notes: [#key-notes] 1. **Padding and Margin**: `paddingStart`, `paddingEnd`, `marginStart`, and `marginEnd` adjust padding and margin relative to the layout direction (LTR or RTL). 2. **Text Alignment**: Use `textAlign: 'auto'` to automatically align text based on the current language direction. 3. **Flexbox Layout**: The `flexDirection` property handles row direction changes. Using `row-reverse` is particularly useful in RTL layouts. 4. **Border and Positioning**: Border and positional properties (like `start`, `end`, `borderStartWidth`, etc.) ensure correct positioning and borders in both LTR and RTL. By leveraging these RTL-supported style properties, your React Native app can automatically handle both left-to-right and right-to-left languages without the need for hardcoding directional adjustments. # Theming (/docs/build/look-and-feel/theming) It includes color schemes for light and dark modes and font configurations. Theming can be customized using the `App Branding` extension in the dashboard. ## Using the Theme [#using-the-theme] To use the theme in your components: 1. Import the necessary hooks and components: ```javascript import { useStyles, createStyleSheet } from "@appmaker-xyz/react-native"; ``` 2. Create a stylesheet using `createStyleSheet`: ```javascript const stylesheet = createStyleSheet((theme) => ({ container: { backgroundColor: theme.colors.background, padding: theme.spacings.xl, }, })); ``` 3. Use the `useStyles` hook in your component: ```javascript const { styles, theme } = useStyles(stylesheet); ``` 4. Apply the styles and theme properties to your components: ```javascript Themed Text ``` ### Example Component [#example-component] ```jsx import React from "react"; import { ThemeText, Layout } from "@appmaker-xyz/ui"; import { createStyleSheet, useStyles } from "@appmaker-xyz/react-native"; const Component = (props) => { const { styles, theme } = useStyles(stylesheet); return ( Component! ); }; const stylesheet = createStyleSheet((theme) => ({ container: { backgroundColor: theme.colors.background, padding: theme.spacings.md, }, })); export default Component; ``` ## Common Theme Properties [#common-theme-properties] ### Font Family [#font-family] Font families are configurable and can be customized using app settings: ```typescript fontFamily: { regular: "SFProDisplay-Regular", // Default, can be customized in App Branding extension medium: "SFProDisplay-Medium", // Default, can be customized in App Branding extension bold: "SFProDisplay-Bold", // Default, can be customized in App Branding extension } ``` ### Spacing and Border Radius [#spacing-and-border-radius] Common sizes are used for both spacing and border radius: ```typescript const commonSizes = { xs: 2, sm: 4, md: 6, lg: 8, xl: 12, "2xl": 16, "3xl": 24, }; ``` These sizes are available in the theme as `spacings` and `borderRadii`. ### Color Schemes [#color-schemes] The theme includes separate color schemes for light and dark modes. These are defined in lightColors and darkColors respectively. Can be customized from `App Branding` extension in the dashboard. To enable dark mode, you need to switch "Enable System Color Scheme Switching" in App Branding extension. If not enabled, the app will use light mode colors. #### Light Mode Colors (Default) [#light-mode-colors-default] - `pageBackground`: ⬤ '#FAFAFA' - `background`: ⬤ '#ffffff' - `text`: ⬤ '#000000' - `lightBackground`: ⬤ '#E9ECF3' - `lightText`: ⬤ '#212121' - `primaryButtonBackground`: ⬤ '#000000' - `primaryButtonText`: ⬤ '#ffffff' - `secondaryButtonBackground`: ⬤ '#475569' - `secondaryButtonText`: ⬤ '#ffffff' - `accent`: ⬤ '#27ae60' - `icon`: ⬤ '#333333' - `separator`: ⬤ '#f4f3f3' - `headerBackground`: ⬤ '#f2f2f2' - `statusbar`: ⬤ '#f2f2f2' - `link`: ⬤ '#007BFF' - `error`: ⬤ '#DC2626' - `success`: ⬤ '#30A479' - `warning`: ⬤ '#ffae42' - `placeholder`: ⬤ '#999999' - `muted`: ⬤ '#C0C0C0' - `loading`: ⬤ '#f4f4f4' #### Dark Mode Colors (Default) [#dark-mode-colors-default] - `pageBackground`: ⬤ '#222222' - `background`: ⬤ '#333333' - `text`: ⬤ '#ffffff' - `lightBackground`: ⬤ '#555555' - `lightText`: ⬤ '#ffffff' - `primaryButtonBackground`: ⬤ '#3730A3' - `secondaryButtonBackground`: ⬤ '#0F172A' - `icon`: ⬤ '#eeeeee' - `separator`: ⬤ '#555555' - `headerBackground`: ⬤ '#222222' - `statusbar`: ⬤ '#222222' - `link`: ⬤ '#4fc3f7' - `error`: ⬤ '#ff6b6b' - `success`: ⬤ '#68b995' - `warning`: ⬤ '#ffc078' - `placeholder`: ⬤ '#aaaaaa' - `muted`: ⬤ '#555555' - `loading`: ⬤ '#333333' When enabling dark mode, make sure to test your app thoroughly to ensure that all components are visible and accessible. To handle dark mode manually in your components, you can use `useColorScheme` hook from `react-native` to get the current mode and adjust the component accordingly. ```javascript import { useColorScheme } from "react-native"; const isDarkMode = useColorScheme() === "dark"; ``` # Button Component (/docs/build/look-and-feel/ui-components/button) It's designed to be flexible and can be used across different parts of the application. ## Key Features [#key-features] - Customizable appearance (filled or outline) - Multiple size options (sm, lg, xl, default) - Loading state with activity indicator - Disabled state - Custom colors for button and text - Custom font type support - Accessibility support via testId ## Props [#props] | Prop | Type | Description | | ---------------------- | --------------------------------- | ------------------------------------------ | | title | string | The text displayed on the button | | onPress | () => void | Function called when the button is pressed | | buttonStyle | ViewStyle | Custom styles for the button container | | textStyle | TextStyle | Custom styles for the button text | | isLoading | boolean | Whether to show a loading indicator | | isOutline | boolean | Whether to use an outline style | | activityIndicatorColor | string | Color of the loading indicator | | size | 'sm' \| 'lg' \| 'xl' \| 'default' | Size of the button | | color | string \| undefined | Background color of the button | | textColor | string | Color of the button text | | fontType | string | Font family for the button text | | testId | string | Test ID for accessibility | | disabled | boolean | Whether the button is disabled | ## Usage [#usage] ```jsx import { Button } from "@appmaker-xyz/ui"; ``` Now let'sadd the functionality to add the bundle to the cart. Let us assign the selected products in the bundle to a variable. ```tsx const customAttributes = Object.keys(state.bundles).map((bundleId) => { const product_bundle = state.bundles[bundleId]; const products = Object.keys(product_bundle.products); //match bundle id with collection id in bundles variable above and take the title of bundle const bundle_title = bundle.find((item) => item.id === bundleId).title; const product_titles = products.map((product) => { //match product id with product id in bundles variable above and take the title of product const product_title = bundle.map((item) => item.products).flat().find((item) => item.id === product).title; return product_title; }); return { key: bundle_title, value: product_titles.join(", ") }; }); ``` Then we can integrate with appmaker web sdk to create products to native cart. First install the web sdk. ```bash npm install @appmaker-xyz/web-sdk ``` Then import the web sdk in the product bundle page. ```tsx import AppmakerWebSdk from "@appmaker-xyz/web-sdk" ``` To add the product to cart , we can use the `addProductToCart` method of the web sdk and to show the message after adding the product to cart, we can use the `showMessage` method of the web sdk. Refer to the [web sdk documentation](/docs/build/webview-and-web-sdk/sdk-methods-and-usage) for more details on the web sdk methods. Let's write a function to add the product to cart. ```tsx const handleAddToCart = () => { AppmakerWebSdk.addProductToCart({ product: product, variant: variant, quantity: 1, customAttributes: customAttributes, }) AppmakerWebSdk.showMessage({title:"Product added to cart"}); } ``` We need to add an onclick event to the add to cart button to add the product to cart. ```tsx ``` Let's check the final product bundle page. ```tsx import React, { useEffect } from "react"; import { ProductCard } from "@/comonents/ProductCard"; import { useProductBundle } from "@/hooks/useProductBundle"; // import { } from "./comonents/ProductCard"; import AppmakerWebSdk from "@appmaker-xyz/web-sdk" const bundle = [ { id: "gid://shopify/Collection/429493911574", title: "Tops", maxItems: 1, products: [ { id: "gid://shopify/Product/7983594962966", title: "Workout Shirt", featuredImage: { id: "gid://shopify/ProductImage/39774607736854", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenWorkoutShirt_400x.jpg?v=1675455464", }, }, { id: "gid://shopify/Product/7983594340374", title: "Puffer Jacket", featuredImage: { id: "gid://shopify/ProductImage/39774605475862", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenPufferjacket01_400x.jpg?v=1675455364", }, }, { id: "gid://shopify/Product/7983594176534", title: "Puffer", featuredImage: { id: "gid://shopify/ProductImage/39774605279254", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenPuffer01_400x.jpg?v=1675455329", }, }, { id: "gid://shopify/ProductImage/1245458466", title: "Half Zip", featuredImage: { id: "gid://shopify/ProductImage/1245458466", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenHalfzip01.jpg?v=1675455104", }, }, ], }, { id: "gid://shopify/Collection/429493944342", title: "Bottoms", maxItems: 2, products: [ { id: "gid://shopify/Product/7983594471446", title: "Shorts", featuredImage: { id: "gid://shopify/ProductImage/39774605836310", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenShorts_400x.jpg?v=1675462426", }, }, { id: "gid://shopify/Product/7983593422870", title: "Leggings", featuredImage: { id: "gid://shopify/ProductImage/39774604754966", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenLeggings03_400x.jpg?v=1675455256", }, }, { id: "gid://shopify/Product/7982856273942", title: "Sweatpants", featuredImage: { id: "gid://shopify/ProductImage/39774602002454", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenSweatpants01_400x.jpg?v=1675455387", }, }, ], }, { id: "gid://shopify/Collection/429531037718", title: "Shoes", maxItems: 1, products: [ { id: "gid://shopify/Product/7983595487254", title: "High Top Sneakers", featuredImage: { id: "gid://shopify/ProductImage/39774608883734", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/Whiteleathersneakers01_400x.jpg?v=1675447604", }, }, { id: "gid://shopify/Product/7983595388950", title: "Gray Runners XPs", featuredImage: { id: "gid://shopify/ProductImage/39774608818198", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/Greyrunners_400x.jpg?v=1675447483", }, }, { id: "gid://shopify/Product/7983595356182", title: "Gray Leather Sneakers", featuredImage: { id: "gid://shopify/ProductImage/39774608785430", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/Greyleathersneakers_400x.jpg?v=1675447462", }, }, { id: "gid://shopify/Product/52415645102314", title: "Canvas Can Sneakers", featuredImage: { id: "gid://shopify/ProductImage/52415645102314", url: "https://cdn.shopify.com/s/files/1/0688/1755/1382/products/GreenCanvasSneaker01.jpg?v=1675454881", }, }, ], }, ]; export default function ProductBundle() { const { state, setProduct, isSelected, isLimitExceeded, setBundle, selectecItemsCount, } = useProductBundle(); useEffect(() => { setBundle(bundle); }, []); const product = { "id": 'gid://shopify/Product/679604980957' // replace with your product id } const variant = { "id": 'gid://shopify/ProductVariant/40026424869026' // replace with your variant id } //pass the selected bundle items as custom attributes const customAttributes = Object.keys(state.bundles).map((bundleId) => { const product_bundle = state.bundles[bundleId]; const products = Object.keys(product_bundle.products); //match bundle id with collection id in bundles variable above and take the title of bundle const bundle_title = bundle.find((item) => item.id === bundleId).title; const product_titles = products.map((product) => { //match product id with product id in bundles variable above and take the title of product const product_title = bundle.map((item) => item.products).flat().find((item) => item.id === product).title; return product_title; }); return { key: bundle_title, value: product_titles.join(", ") }; }); const handleAddToCart = () => { AppmakerWebSdk.addProductToCart({ product: product, variant: variant, quantity: 1, customAttributes: customAttributes, }) AppmakerWebSdk.showMessage({ title: "Product added to cart" }); } return (

Perfect Gift Box

{bundle.map((item) => (

{item.title} ({selectecItemsCount(item.id)}/{item.maxItems})

{item.products?.map((product) => ( { setProduct(item.id, product.id, isSelected); }} /> ))}
))}

{state.totalItems} Selected

$124.00

); } ``` After adding to cart, you can see the custom attributes below the product. ![](/docs-assets/app-build/product-bundle-checkout.png) # Hide Header and Footer using Appmaker Web SDK (/docs/build/webview-and-web-sdk/hide-header-footer-using-sdk) You can also use the Appmaker Web SDK to do custom actions. For example, you can use the Appmaker Web SDK to open the cart page, open the product page, and get the platform. Let's get started by adding the Appmaker Web SDK to your shopify website. ### Use Appmaker Web SDK inside the theme.liquid file of your Shopify theme [#use-appmaker-web-sdk-inside-the-themeliquid-file-of-your-shopify-theme] Import the Appmaker Web SDK using the script tag. You can import the Appmaker Web SDK using the following script tag. ```js ``` You can use the following code to check if the code is running inside the Appmaker WebView. ```js ``` ### How to hide header and footer by editing the theme.liquid file [#how-to-hide-header-and-footer-by-editing-the-themeliquid-file] 1. Find your theme.liquid file in your theme folder. 2. Add the following code to your theme.liquid file. ```js ``` 3. Save the file. You can refer to the [Appmaker Web SDK documentation](/docs/build/webview-and-web-sdk/sdk-methods-and-usage) to learn more about Appmaker Web SDK methods. # How to send post message from webview (/docs/build/webview-and-web-sdk/how-to-send-post-message-from-webview) ## Introduction [#introduction] In this guide, we will learn how to send a post message from a webview. ## How to send post message from webview [#how-to-send-post-message-from-webview] To send a post message, use the following code: ```jsx window.ReactNativeWebView.postMessage("my-message"); ``` To receive this message, apply the following filter: ```jsx appmaker.addFilter( 'appmaker-webview-message-data', 'myCustomFilter', // Replace with your extension id myCustomFilterHandler, // Replace with your custom filter handler function ); ``` ```jsx export function myCustomFilterHandler(data, { event, url }) { // Handle the data received from the post message console.log(`Custom webview event data`, data, url); // Add your custom logic here if (url.includes('yourdomain.com')) { // Do something } return data; } ``` # Webview & Web SDK (/docs/build/webview-and-web-sdk) # Installation of appmakerWebSdk (/docs/build/webview-and-web-sdk/installation-of-appmaker-web-sdk) ## Requirements [#requirements] This library is only compatible with the Appmaker webview. ## Installation [#installation] To install the Appmaker Web SDK, run the following command: ```bash npm install @appmaker-xyz/web-sdk ``` ## Usage [#usage] To use the Appmaker Web SDK, import the library in your project: ```js import { AppmakerWebSdk } from '@appmaker-xyz/web-sdk'; ``` # Appmaker WebSDK (/docs/build/webview-and-web-sdk/installation) ## Requirements [#requirements] This library is only compatible with the Appmaker webview. ## Installation [#installation] There are two ways to install the Appmaker Web SDK: 1. Create a single page React app and then connect with appmaker web SDK 2. Connect existing page with appmaker web SDK using script [https://unpkg.com/@appmaker-xyz/web-sdk@latest/dist/index.umd.js](https://unpkg.com/@appmaker-xyz/web-sdk@latest/dist/index.umd.js) ## Configure the Appmaker Web SDK using React [#configure-the-appmaker-web-sdk-using-react] 1. Create a sample [react app using next.js](https://react.dev/learn/start-a-new-react-project). You can use the following command to create a sample react app. ```bash npx create-next-app my-app cd my-app ``` 2. Start the development server using the following command. ```bash npm start ``` 3. You can see the sample app running on [http://localhost:3000](http://localhost:3000) 4. Now you can edit the `src\App.js` of the my-app project and add your custom code. For example, you can simply add a button to the `src\App.js` file. ```jsx import logo from './logo.svg'; import './App.css'; function App() { return (
logo

Edit src/App.js and save to reload.

); } export default App; ``` 5. save the file and you can see the button on the page. 6. Now you can add the Appmaker Web SDK to the project. You can use the following command to install the Appmaker Web SDK. ```bash npm install @appmaker-xyz/web-sdk ``` 7. Import the Appmaker Web SDK in the `src\App.js` file. ```jsx import AppmakerWebSDK from "@appmaker-xyz/web-sdk"; ``` 8. Let's add an action to button to open the cart. ```js import logo from './logo.svg'; import './App.css'; import AppmakerWebSDK from "@appmaker-xyz/web-sdk"; function App() { return (
logo p> Edit src/App.js and save to reload.

); } export default App; ``` 9. Now when you click on open cart button from the appmaker webview it will open the cart. You can also refer to another example [here](/docs/build/webview-and-web-sdk/create-a-product-bundle). ## Configure the Appmaker Web SDK using script [#configure-the-appmaker-web-sdk-using-script] 1. Create a sample html page and add the following script tag to the page. ```html ``` 2. Now you can use the Appmaker Web SDK in the page. ```html ``` 3. Now when you open the page from the appmaker webview it will open the cart. You can also hide header and footer of a page using appmaker web SDK , refer to the example [here](/docs/build/webview-and-web-sdk/hide-header-footer-using-sdk). ## Appmaker WebSDK Methods [#appmaker-websdk-methods] To know more about appmaker web SDK and it's methods, refer to the [documentation](/docs/build/webview-and-web-sdk/sdk-methods-and-usage). # Appmaker Web SDK Methods and Usage (/docs/build/webview-and-web-sdk/sdk-methods-and-usage) ### `isAppmakerWebview()` [#isappmakerwebview] Returns true if the app is running inside the Appmaker webview. #### Example: [#example] ```javascript AppmakerWebSdk.isAppmakerWebview(); ``` ### `getPlatform()` [#getplatform] Returns the platform the app is running on. Possible values are `android` and `ios`. #### Example: [#example-1] ```javascript AppmakerWebSdk.getPlatform(); ``` ### `openCart()` [#opencart] Opens the cart page. #### Example: [#example-2] ```js AppmakerWebSdk.openCart(); ``` ### `openProductById(productId)` [#openproductbyidproductid] Opens the product page for the product with the given id. #### Example: [#example-3] ```js AppmakerWebSdk.openProductById('gid://shopify/Product/6793295167650') ``` ### `openProductByHandle(productHandle)` [#openproductbyhandleproducthandle] Opens the product page for the product with the given handle. #### Example: [#example-4] ```js AppmakerWebSdk.openProductByHandle("t-shirt") ``` ### `openCollectionById(collectionId)` [#opencollectionbyidcollectionid] Opens the collection page for the collection with the given id. #### Example: [#example-5] ```js AppmakerWebSdk.openCollectionById('gid://shopify/Collection/269255016610') ``` ### `openCollectionByHandle(collectionHandle)` [#opencollectionbyhandlecollectionhandle] Opens the collection page for the collection with the given handle. #### Example: [#example-6] ```js AppmakerWebSdk.openCollectionByHandle("t-shirts") ``` ### `applyCoupon(couponCode, { goBackAfterApply = false } )` [#applycouponcouponcode--gobackafterapply--false--] Applies the given coupon code to the cart. If `goBackAfterApply` is true, the app will go back to the previous page after the coupon is applied. #### Example: [#example-7] ```js AppmakerWebSdk.applyCoupon("SUMMER20", { goBackAfterApply: true }); ``` ### `removeCoupon(couponCode)` [#removecouponcouponcode] Removes the given coupon code from the cart. #### Example: [#example-8] ```js AppmakerWebSdk.removeCoupon("SUMMER20"); ``` ### `addProductToCart({ product, variant, quantity, customAttributes })` [#addproducttocart-product-variant-quantity-customattributes-] Adds the given product to the cart. `product` and `variant` are the product and variant objects returned by the Shopify Storefront API. `quantity` is the quantity of the product to add to the cart. `customAttributes` is an object containing custom attributes to add to the line item. #### Example: [#example-9] ```js const customAttributes = [ { "key": "_appmaker", "value": "true" } ] const variant = { id: 'gid://shopify/ProductVariant/40026424869026', } const product = { id: 'gid://shopify/Product/6796049809570', } AppmakerWebSdk.addProductToCart({ product:product, variant:variant, quantity:1, customAttributes:customAttributes }); // make sure to pass the values to its respective keys ``` ### `removeProductFromCart({lineItemId, product, variant, quantity, updateCartPageStateRequired})` [#removeproductfromcartlineitemid-product-variant-quantity-updatecartpagestaterequired] Removes the product with the given line item id from the cart. #### Example: [#example-10] ```js AppmakerWebSdk.removeProductFromCart( { lineItemId:'gid://shopify/CheckoutLineItem/400264248690260?checkout=9454b13ff3037f9ec0636b57b075a2a9',product:product , variant:variant ,updateCartPageStateRequired:true}) // refer to addProductToCart for product and variant ``` ### `updateProductQuantityInCart({ lineItemId, product, variant, quantity, updateCartPageStateRequired})` [#updateproductquantityincart-lineitemid-product-variant-quantity-updatecartpagestaterequired] Updates the quantity of the product with the given line item id in the cart. #### Example: [#example-11] ```js AppmakerWebSdk.updateProductQuantityInCart({ lineItemId:'gid://shopify/CheckoutLineItem/400264248690260?checkout=9454b13ff3037f9ec0636b57b075a2a9',product:product , variant:variant , quantity:2,updateCartPageStateRequired:true}) // refer to addProductToCart for product and variant ``` ### `clearCart()` [#clearcart] Clears the cart. #### Example: [#example-12] ```js AppmakerWebSdk.clearCart(); ``` ### `setLineItemProperties({ lineItemId, product, variant, properties })` [#setlineitemproperties-lineitemid-product-variant-properties-] Sets the custom attributes of the product with the given line item id in the cart. #### Example: [#example-13] ```js const properties = [ { "key": "custom", "value": "appmaker" } ] AppmakerWebSdk.setLineItemProperties({lineItemId:'gid://shopify/CheckoutLineItem/400264248690260?checkout=9454b13ff3037f9ec0636b57b075a2a9',product:product, variant:variant, properties:properties}); // refer to addProductToCart for product and variant ``` ### `openInAppPage({ pageId, title, replacePage = false })` [#openinapppage-pageid-title-replacepage--false-] Opens the in-app page with the given id. If `replacePage` is true, the app will replace the current page with the in-app page. #### Example: [#example-14] ```js AppmakerWebSdk.openInAppPage({ pageId: "home", title: "In-app home page", replacePage: true }); ``` ### `openHome({ replacePage = false })` [#openhome-replacepage--false-] Opens the home page. If `replacePage` is true, the app will replace the current page with the home page. #### Example: [#example-15] ```js AppmakerWebSdk.openHome({ replacePage: false }); ``` ### `showMessage({ title })` [#showmessage-title-] Shows a message with the given title. #### Example: [#example-16] ```js AppmakerWebSdk.showMessage({ title: "Hello world!" }); ``` ### `goBack()` [#goback] Goes back to the previous page. #### Example: [#example-17] ```js AppmakerWebSdk.goBack(); ``` ### `copyToClipboard({ text })` [#copytoclipboard-text-] Copies the given text to the clipboard. #### Example: [#example-18] ```js AppmakerWebSdk.copyToClipboard({ text: "Hello world!" }); ``` ### `openCheckout()` [#opencheckout] Opens the checkout page. #### Example: [#example-19] ```js AppmakerWebSdk.openCheckout(); ``` ### `openSearch()` [#opensearch] Opens the search page. #### Example: [#example-20] ```js AppmakerWebSdk.openSearch(); ``` ## Usage [#usage] ```javascript import AppmakerWebSdk from "@appmaker-xyz/web-sdk"; AppmakerWebSdk.openCart(); ``` # App Theme (/docs/concepts/app-theme) It includes the colors, fonts, and other visual elements that are used in the app. You can customize the app theme by changing the colors, fonts, and other visual elements such as individual components, layouts, and screens. The app look and feel like collection listing page, product listing page, product detail page, cart page, and checkout page can be customized using the app theme. See examples of the app themes of live app below to get an idea of what you can do with the theme. These apps are live and you can download them from the app stores. ![App Theme 01](/img/theme/theme-01.png) ![App Theme 02](/img/theme/theme-02.png) ![App Theme 03](/img/theme/theme-03.png) ![App Theme 04](/img/theme/theme-04.png) ## Starting a new theme [#starting-a-new-theme] To install the theme, you need to have a working app. If you don't have an app, you can create one using the [App Maker CLI](/docs/get-started/install-appmaker-cli). A brief overview of the steps to create a new theme is given below. Prior to creating a new theme or extension locally, you must first create it on https://partners.appmaker.xyz/. ```bash appmaker init ``` Select the `theme` from the list of options in the prompt, and select the theme you want to install. ```bash cd ``` ```bash npm install ``` > ### Running the app [#running-the-app] > > Refer to the docs for more details on running the app > Refer to the [Running the app](/docs/get-started/running-app) section for more details on running the app. ## Customizing the theme [#customizing-the-theme] Now that you have set up the starter app, you can start customizing the theme. You can customize the pages and components(blocks) of the app using the theme. Theme files will be located in the `packages/theme-id` folder. The recommended structure of the theme is given below. If the you could not find the folders and files mentioned below, you can create them as required. #### Theme structure [#theme-structure] ```bash title="" packages └── ├── src │ ├── assets │ │ ├── fonts │ │ │ └── Roboto-Regular.ttf │ │ └── images │ │ ├── logo.png │ │ └── star.svg │ ├── blocks │ │ └── index.js │ ├── components │ │ └── ProductGridItem.js │ ├── pages │ │ └── index.js │ └── index.js ├── appmaker.json └── package.json ``` The theme structure is similar to the app structure. The theme has the following files and folders. - `assets` - Contains the assets used in the theme. The assets can be images, fonts, and other files. - `blocks` - Contains the blocks used in the theme. The blocks are the individual components that are used in the app. The blocks are the building blocks of the app. - `components` - Contains the components used in the theme. The components are the individual components that are used in the app. The components are the building blocks of the app. - `pages` - Contains the pages used in the theme. The pages are the individual components that are used in the app. The pages are the building blocks of the app. - `src` - Contains the theme configuration. # Default page ids of the app (/docs/concepts/default-page-ids) ## List of default page ids [#list-of-default-page-ids] In certain situations, you might encounter the need to substitute a current page, which necessitates the knowledge of its unique ID. In this illustration, we will examine key pages and their respective IDs, accompanied by a concise description in the description column. | Page Name | Page ID | Description | | --------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Product List | productList | Page displaying a list of products | | Product Detail | productDetail | Page showing the details of a specific product | | Cart Page | cartPageCheckout | Page for managing the items in the shopping cart | | Drawer Menu | DrawerMenu | Side menu or navigation drawer of the app | | Login Page | LoginPage | Page for user login | | Forget Password | ForgetPassword | Page for resetting a forgotten password | | Register | Register | Page for user registration | | My Account | myAccount | Page displaying user account information | | Search Page | searchPage | Page for searching products or content | | Order List | OrderList | Page listing the user's orders | | Order Detail | orderDetail | Page showing the details of a specific order | | Checkout | Checkout | Page for the checkout process | | Wishlist | WishList | Page displaying the user's wishlist | | Coupon Listing | CouponListing | Page listing available coupons | | Login Options | LoginOptions | Page displaying different login options | | Home | home | Home page of the app | | SplashScreen | splashScreen | Splash screen of the app | | TabHome | TabHome | Bottom tab home page | | Onboarding | onboarding | Onboarding page | | emptyCart | emptyCart | Page displayed when the cart is empty | | ResetPassword | ResetPassword | Page for resetting a forgotten password | # Hooks (/docs/concepts/filters-and-functions) ## Appmaker Hooks: Functions and Filters [#appmaker-hooks-functions-and-filters] Appmaker Hooks are functions that can be used to modify the behavior of the Appmaker platform. They are used to add new features to the platform, modify existing features, and remove features that are not needed. ## Adding a function hook [#adding-a-function-hook] To add a function hook, you need to use the `appmakerFunctions.registerAppmakerFn` function. This function takes three parameters: - `trigger` - The name of the function that you want to modify. - `namespace` - The name of the package that is adding the hook. - `function` - The function that will be called when the trigger is called. ```js `appmakerFunctions.registerAppmakerFn({ trigger, namespace, function })` ``` The function that is passed to the `appmakerFunctions.registerAppmakerFn` takes the parameters that are passed to the trigger function. The function should return the modified parameters. ```js function myFunctionHook(params) { // Modify the params return params; } ``` You can refer to the [Functions](/docs/reference/functions) section for a list of available functions. ## Adding a filter hook [#adding-a-filter-hook] To add a filter hook, you need to use the `appmaker.addFilter` function. This function takes three parameters: - `trigger` - The name of the function that you want to modify. - `namespace` - The name of the package that is adding the hook. - `function` - The function that will be called when the trigger is called. ```js `appmaker.addFilter({trigger,namespace,function})` ``` You can refer to the [Filters](/docs/reference/filters) section for a list of available filters. # Concepts (/docs/concepts) # Page Types and Page Variants Guide (/docs/concepts/page-variants) ## Overview [#overview] Page types and page variants provide a flexible system for creating conditional pages based on specific requirements. This guide explains how to implement and use them effectively. ## Page Types Configuration [#page-types-configuration] ### Helper Functions [#helper-functions] First, define helper functions to check specific conditions. These functions will be used to determine which page type to load. ```javascript const checkMyProductHasBeautyProductTag = (blockData) => { // Checks if product has BeautyProduct tag return blockData?.node?.tags?.includes('BeautyProduct'); }; const checkMyProductHasEssentialProductTag = (blockData) => { // Checks if product has EssentialProduct tag return blockData?.node?.tags?.includes('EssentialProduct'); }; // Register helper functions appmaker.addFilter( 'parse-helper-functions', 'theme-helper-fn', function (value) { return { ...value, checkMyProductHasBeautyProductTag, checkMyProductHasEssentialProductTag, }; }, ); ``` ### Page Configuration Structure [#page-configuration-structure] The main configuration object (`pagesData`) consists of three main sections: - `pageTypes`: Defines different page types and their conditions - `pageVariants`: Defines the block structure for each page type - `blocks`: Contains the actual block definitions - `dataSource`: Contains data source configurations ```javascript const pagesData = { pageTypes: [ { // Reserved empty page type - DO NOT MODIFY type: "empty", pageSource: "pageVariants", condition: "{{ lodash.isEmpty(blockData) || lodash.isEmpty(blockData.node) }}", }, { // Custom Beauty Product Page type: "myBeautyPageType", pageSource: "pageVariants", condition: "{{checkMyProductHasBeautyProductTag(blockData)}}", }, { // Custom Essential Product Page type: "myEssentialPageType", pageSource: "pageId", pageId: "EssentialProductPage", condition: "{{checkMyProductHasEssentialProductTag(blockData)}}", } ], pageVariants: { // Reserved empty variant - DO NOT MODIFY empty: { blocks: [ { name: "appmaker/in-app-page", attributes: { pageId: "ProductNotFound", }, }, ], }, // Custom Beauty Product Page Variant myBeautyPageType: { blocks: [ { name: "appmaker/my-block", attributes: {}, }, ], } }, blocks: [ // Define your blocks here ], dataSource: { // Define your data source configuration here }, }; export default pagesData; ``` ## Important Notes [#important-notes] 1. **Reserved Page Types** - `empty` and `error` are reserved page types - Do not override these types when using pageVariants and pageTypes - Always include the default empty type configuration 2. **Page Sources** Two types of page sources are available: - `pageVariants`: Uses the block structure defined in pageVariants - `pageId`: References an externally defined page 3. **Conditions** - Conditions are evaluated using helper functions - Use proper error handling in condition functions - Conditions have access to `blockData` object 4. **Best Practices** - Keep helper functions simple and focused - Use meaningful names for page types - Document conditions and their expected outcomes - Test all possible condition scenarios # Register a custom action (/docs/concepts/register-custom-action) ## Description [#description] This doc will help you to register a custom action in your appmaker extension and use it in your app. ## Steps [#steps] 1. Create an actions folder and add index.js inside actions in your project root directory. Eg: `src/actions/index.js` 2. Add the following code to the file. ```javascript import { appmaker } from '@appmaker-xyz/core'; function MY_CUSTOM_ACTION( { action, params }, { handleAction, appStorageState }, ) { console.log("params", params); // you can write the logic for your action here alert('My custom action is called'); } function MY_SECOND_ACTION( { action, params }, { handleAction, appStorageState }, ) { // You can also call another action from using handleAction handleAction({ action: 'MY_CUSTOM_ACTION', params: { key: 'value', }, }); } export function registerActions() { appmaker.actions.registerAction('MY_CUSTOM_ACTION', MY_CUSTOM_ACTION); appmaker.actions.registerAction('MY_SECOND_ACTION', MY_SECOND_ACTION); } ``` 3. Import the `registerActions` function in your root file `src/index.js` and call it in `activate` function. ```javascript import { registerActions } from './actions'; export function activate() { registerActions(); } ``` ## Usage [#usage] You can now use the action in your app using `onAction`. ```javascript onAction({ "action": "MY_CUSTOM_ACTION", "params": { "key": "value" } }); ``` # Appmaker Theme Overview (/docs/concepts/theme-overview) To build themes for Appmaker, developers use a combination of React Native components and JSON. These tools allow them to create a customized look and feel that matches their clients' requirements. React Native provides developers with several resources and guidelines to help them develop high-quality themes efficiently. As a React Native app developer, you have the flexibility to create custom themes that cater to the specific needs and preferences of your clients. You can also personalize existing blocks and pages to create a unique look and feel for your app or create new blocks and pages to enhance your app's functionality. --- ### Appmaker Theme Anatomy [#appmaker-theme-anatomy] An app's theme determines its structure, features, and design. The code for an Appmaker theme follows a standard directory structure and includes supporting assets such as images, stylesheets, and fonts. As a developer, you need to optimize your theme's structure, features, and design to meet the specific needs of your target audience or use case. The best themes are customized to the users' preferences and requirements. ### Page Structure [#page-structure] An app's theme is composed of pages and blocks. Pages are the main building blocks of an app and are used to display content to the user. Blocks are the building blocks of pages and are used to display content to the user. ![Appmaker Theme Anatomy](/img/theme/theme-page-structure.png) 1. **Page**: page is the main building block of an app and is used to display content to the user. 2. **Layout**: layout is used as the container for the blocks. 3. **Repeatable** block layout: repeatable block layout is used to display a list of blocks. 4. **Block**: block is the main visual element of a page and is used to display content to the user. 5. **Sticky footer layout**: sticky footer layout is used to display a footer at the bottom of the page. ### Supporting assets [#supporting-assets] It's possible to enhance the appearance of components and features or store reusable code snippets that can be utilized in multiple components by incorporating supporting assets into your theme. For example, you can change create a custom font and use it in your theme to change the font of the app's text. In another scenario, you can create a custom button component and use it in your theme block components to ensure that all buttons in the app have the same look and feel. # Use the docs with AI tools (/docs/get-started/ai-tools) AI coding assistants give better answers about Appmaker when they can read these docs. Connect your assistant to the docs MCP server, and it searches and reads the current docs while it helps you build themes and extensions. ## MCP server [#mcp-server] The docs MCP server is at: ```text https://dev.appmaker.xyz/mcp ``` It is free, read-only and needs no sign-in. It uses the Streamable HTTP transport. ### Connect your tool [#connect-your-tool] Run this in a terminal: ```bash claude mcp add --transport http appmaker-developer-docs https://dev.appmaker.xyz/mcp ``` Add `--scope project` to share it with your team through the project's `.mcp.json` file. Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project: ```json title=".cursor/mcp.json" { "mcpServers": { "appmaker-developer-docs": { "url": "https://dev.appmaker.xyz/mcp" } } } ``` Add the server to `.vscode/mcp.json` in your project: ```json title=".vscode/mcp.json" { "servers": { "appmaker-developer-docs": { "type": "http", "url": "https://dev.appmaker.xyz/mcp" } } } ``` Then use it from GitHub Copilot chat in agent mode. In Claude on the web or the Claude desktop app, open **Settings → Connectors**, choose **Add custom connector**, and enter: - **Name:** Appmaker developer docs - **URL:** `https://dev.appmaker.xyz/mcp` Other tools that support remote MCP servers over HTTP work the same way: add a server with the URL above. ### Tools [#tools] | Tool | What it does | | --- | --- | | `search_docs` | Searches the docs and returns the best-matching pages, with links to the matching sections. | | `get_page` | Returns a page as Markdown, from its URL or path (for example `/docs/get-started/install-appmaker-cli`). | | `list_pages` | Lists the docs sections, or every page in a section. | Try asking your assistant something like "Using the Appmaker developer docs, how do I add a custom block to the product page?" ## Docs as Markdown [#docs-as-markdown] To give the docs to a tool that doesn't support MCP, use the Markdown versions: - [`/llms.txt`](https://dev.appmaker.xyz/llms.txt) lists every page with a link to it. - [`/llms-full.txt`](https://dev.appmaker.xyz/llms-full.txt) is the whole site as one Markdown file. - Add `.md` to any page URL to get that page as Markdown, for example [`/docs/get-started.md`](https://dev.appmaker.xyz/docs/get-started.md). # Appmaker Release (/docs/get-started/appmaker-release) To release your app, you need to follow the steps below: 1. In appmaker CLI, run the following command to release your app ```bash appmaker release ``` 2. You will be prompted to enter the release notes for your app. Enter the release notes and press enter. ## Submit for approval [#submit-for-approval] To submit your app for approval, you need to follow the steps below: 1. In appmaker CLI, run the following command to submit your app for approval ```bash appmaker publish ``` 2. You will be prompted to select the version of your app. Select the version you want to submit for approval and press enter. 3. You have successfully submitted your app for approval. # Configuring the app (/docs/get-started/configuration) ## Set project ID [#set-project-id] Set the default project ID for the appmaker cli by changing the project ID in the `.env` file in the root of the project. ```js EXPO_PUBLIC_APPMAKER_PROJECT_ID=177768 // you can set your project id here ``` {/* If you want to add a new extension or package to your project, you can do so by following the steps below or you can skip this step and add the extension or package later. ## Add an extension/package 1. To add an extension or a package, make sure you have access to the `https://github.com/Appmaker-Partners/` repository, then from the root of your project, run the following command: ```bash npm run add-package npm install ``` 2. Manually add a package.json file to the package folder with the following content and replace `` with the name of the package you want to add. ```json { "name": "@appmaker-partners/", "version": "0.1.0", "main": "index.js" } ``` 3. Save the file. 4. Push the changes to your repository. ```bash git add . git commit -m "Added " git push ``` You have now added a new extension or package to your project. ### Install package You can install your extension to the appmaker starter app by following the steps below: 1. Import and register the extension in `src/initApp.js` file of the appmaker starter app. To register the package, add the following code to the `src/initApp.js` file: ```js import '@appmaker-partners/'; ``` 2. Save the file. */} # Create a package (/docs/get-started/create-package) To create a local development environment for your extension or theme, execute the following command: Prior to creating a new theme or extension locally, you must first create it on https://partners.appmaker.xyz/. ```bash appmaker init ``` Select the theme or extension you want from the list of available options on your partner account, also select expo(default) from the list of available options for the sdk version and it will automatically be created in your current directory. [Example video](https://drive.google.com/file/d/1GbfgXNNHp2ZWp9_y3VUFNVPIsZ_bN1ey/view?usp=sharing) Once you have created the theme/extension install the dependencies by running the following command: ```bash cd ``` ```bash yarn install ``` Source code for the theme/extension will be inside the `packages/` directory. # Create appmaker partner account (/docs/get-started/create-partner-account) ### Step 1 - Navigate to partner dashboard Signup [#step-1---navigate-to-partner-dashboard-signup] To create a new account on Apmmaker partner dashboard, navigate to the [Appmaker partner dashboard](https://partners.appmaker.xyz/signup). We recommend the `admin` of the organisation signing up by creating the account from the above link and inviting the members from the partner dashboard to avoid duplicate organisations being created. You can follow the steps outlined in the [Invite Team Member to partner dashboard](/docs/partner-dashboard/invite-member) guide to add new members to your organisation. ### Step 2 - Fill the required details [#step-2---fill-the-required-details] Enter your `Company name` and `Full name` in the respective fields as showin in the screenshot below. ![Appmaker partner dashboard](/docs-assets/partnerdashboardsignup.png) ### Step 3 - Set the password [#step-3---set-the-password] Enter your `Email address` and `Password` in the respective fields. ### Step 4 - Create Account [#step-4---create-account] Click on "`Create an account`" button and you will be taken to the homepage of Appmaker partner dashboard. # Getting Started (/docs/get-started) ### Partner Account and Extension creation [#partner-account-and-extension-creation] The partner account helps in the creation and managing of extensions and themes.It can be set up with a few simple steps. - **Step 1** Create an account on the Appmaker [`partner dashboard`](/docs/get-started/create-partner-account). - **Step 2** From the partner dashboard, [`create an extension`](/docs/partner-dashboard/create-extension) or theme based on your specific use case. ### Installation and setting up of the starter app [#installation-and-setting-up-of-the-starter-app] Once the extension / theme is created, it can be installed and tested locally within the starter app. - **Step 3** Install the [`appmaker CLI`](/docs/get-started/install-appmaker-cli) via the terminal to set up the Starter app. - **Step 4** Configure the [`project ID`](/docs/get-started/configuration) for the particular project to ensure proper functioning. > Note : If you are not working on a specific project, you can skip this step. - **Step 5** [`Download and run`](/docs/get-started/running-app) the appmaker starter app. - **Step 6** Enhance the extension by adding desired functionalities and test it locally within the starter app. ### Appmaker Release [#appmaker-release] To get the test build from partner dashboard, the appmaker release command is used. - **Step 7** Execute the [`appmaker release`](/docs/get-started/appmaker-release) command. ### App Build [#app-build] App build allows developers to create production builds from within the Appmaker partner dashboard, allowing them to quickly test and iterate changes they have made to themes and extensions. - **Step 8** Obtain the [`app build`](/docs/partner-dashboard/app-build) from the partner dashboard. ### App Submission [#app-submission] - **Step 9** Submit the final version for approval using the `appmaker publish` command. > Note : Once submitted, the version will undergo an internal review process by our team before approval. The SLA for review and approval is `3 to 5 working days` from the time of submission using appmaker publish. Once the extension / theme is approved, it will be publicly available and listed in the extensions library of the Appmaker dashboard. ### Use the docs with AI tools [#use-the-docs-with-ai-tools] Connect Claude, Cursor, VS Code or another AI assistant to the [docs MCP server](/docs/get-started/ai-tools), so it can search and read these docs while it helps you build. # Installation (/docs/get-started/install-appmaker-cli) ## Requirements [#requirements] Before getting started, you will need to make sure you have the following requirements installed on your machine: * [Node.js](https://nodejs.org/en/download/) (Node version can be managed using [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) ) * [Yarn](https://classic.yarnpkg.com/en/docs/install) ## Getting started [#getting-started] ### Install appmaker cli [#install-appmaker-cli] To get started, you will need to install the `appmaker-cli` package. To do this, open a terminal window and run the following command: ```bash npm config set '@appmaker-partners:registry' 'https://flash.appmaker.xyz' ``` ```bash npm i -g @appmaker-partners/cli ``` 1. Download and install nvm-setup.exe from [here](https://github.com/coreybutler/nvm-windows) 2. Open command prompt as administrator and run the following command to install node ```bash nvm install latest ``` 3. Run the following command to use the node version you installed ```bash nvm use 18.16.0 ``` Replace 18.16.0 with the node version you want to use. 4. Run the following command to install appmaker cli ```bash npm config set '@appmaker-partners:registry' 'https://flash.appmaker.xyz' ``` ```bash npm i -g @appmaker-partners/cli ``` ### Login to appmaker cli [#login-to-appmaker-cli] To login to the `appmaker-cli`, run the following command: ```bash appmaker login ``` This will open a browser window where you can login to your appmaker account. Once you have logged in, you will be redirected to a page where you can create the token. Copy the token and paste it in the terminal window where you are logged in to the `appmaker-cli`. # Running the app (/docs/get-started/running-app) ### Option 1: Download the apk file and start the react-native development server. (Recommended) [#option-1--download-the-apk-file-and-start-the-react-native-development-server-recommended] Follow the steps below to run the app on your android device. 1. Take a development build for you project from partner dashboard. Refer the doc [here](/docs/partner-dashboard/app-build) to know how to take an app build. For iOS, you can follow the steps [here](/docs/partner-dashboard/app-debug-build-ios) to run the app on the simulator. 2. Install the apk file on your device. 3. Start the react-native development server by running the following command: ```bash yarn start ``` 4. Open development build on your device. 5. Shake the device to open the developer menu and click on "Settings" 6. Enter the IP address of the machine followed by the port number `:8081` and click on "Ok". 7. Go back to the app and click on "Reload" on developer menu. (Shake the device again to open the developer menu) 8. You should now see the app running on your device. 9. Any changes you make inside `packages/` folder will be reflected in the app. (You can press `r` on the terminal or click on "Reload" on developer menu to manually reload the app) ### Option 2: To build and run the app on an Android/iOS emulator [#option-2-to-build-and-run-the-app-on-an-androidios-emulator] Follow the steps below to run the app on your emulator. 1. For android, take an android development build for you project from partner dashboard. Refer the doc [here](/docs/partner-dashboard/app-build) to know how to take an app build. 2. Drag and drop the apk file on the emulator to install the app. 3. Start the react-native development server by running the following command: ```bash yarn start ``` 4. Open your development app on the emulator. For iOS, you can follow the steps [here](/docs/partner-dashboard/app-debug-build-ios) to run the app on the simulator. ## Next steps [#next-steps] Now that you have set up the starter app, you can start customizing it or create a custom plugin. To learn more about customizing the app theme, check out the [Customizing app theme](/docs/build) section. {/* To learn more about creating a custom plugin, check out the [Creating a custom plugin](/) section. */} # Introduction (/docs) Appmaker turns Shopify stores into native mobile apps. Apps are built with [React Native](https://reactnative.dev/), and the platform is extensible: you can change how any part of an app looks and behaves, or add new features, through themes and extensions. These docs are for developers building on Appmaker: agencies and partners customizing a merchant's app, and teams building reusable add-ons. ## How it works [#how-it-works] Your code ships as a **package**, either a theme or an extension: - A **theme** controls how the app looks. It is made of **pages** (product page, cart, account and so on) and the **blocks** that fill them. - An **extension** adds or changes behavior, such as analytics, login providers, reviews or custom checkout logic. Both plug into the app through the same building blocks: - **Blocks**: React Native components placed on pages, either in code or by merchants in the App Builder. - **Actions**: named operations a block can trigger, such as add to cart or open a page. - **Filters and functions**: hooks that change data or replace the app's default behavior. - **React hooks**: from `@appmaker-xyz/shopify`, for cart, product, user, search and more. ## Your first package [#your-first-package] 1. [Create a partner account](/docs/get-started/create-partner-account) and [create an extension or theme](/docs/partner-dashboard/create-extension) in the partner dashboard. 2. [Install the Appmaker CLI](/docs/get-started/install-appmaker-cli) and [configure your project](/docs/get-started/configuration). 3. [Run the starter app](/docs/get-started/running-app) and build your package against it locally. 4. Use [`appmaker release`](/docs/get-started/appmaker-release) to get a test build, then create builds from the [partner dashboard](/docs/partner-dashboard/app-build). } title="Get started" href="/docs/get-started"> Set up your account, the CLI and the starter app. } title="Concepts" href="/docs/concepts"> Themes, pages, blocks, actions, filters and functions. ## Explore the docs [#explore-the-docs] } title="Build your app" href="/docs/build"> Pages, navigation, blocks, product page, cart, account, styling and data, grouped by the part of the app you are changing. } title="Integrations" href="/docs/integrations"> Analytics vendors, push notifications and reviews. } title="Native code" href="/docs/native-code"> Native libraries, permissions and Expo config plugins. } title="Partner dashboard" href="/docs/partner-dashboard"> Extensions, team access and app builds. } title="Reference" href="/docs/reference"> Actions, filters, functions, React hooks, the config form and the CLI. } title="Troubleshooting" href="/docs/troubleshooting"> Fixes for common setup and build problems. ## Stay up to date [#stay-up-to-date] See the [Changelog](/docs/changelog) for release notes and breaking changes, such as the move to the Shopify Cart API. # Analytic Events and Context (/docs/integrations/analytics/appmaker-analytics-events) ## Overview [#overview] These events are used to track user behavior and to send data to the analytics provider. ## Events [#events] #### `product_added_to_cart` [#product_added_to_cart] The `product_added_to_cart` event is triggered when a product is added to the cart. | Field Name | Data Type | Description | | ---------------- | --------- | ----------------------------------------------------------------- | | currency | string | The currency in which the item is priced. | | item_brand | string | The brand of the item. | | item_id | string | A unique identifier for the item. | | item_name | string | The name of the item. | | item_variant | string | The variant of the item, if applicable. | | price | float | The price of the item. | | quantity | integer | The number of items being purchased. | | value | float | The total value of the items being purchased (price \* quantity). | | variant_currency | string | The currency in which the variant is priced. | | variant_id | string | A unique identifier for the variant. | | variant_price | float | The price of the variant. | **_Example:_** ```json { "currency": "INR", "item_brand": "brand name", "item_id": "1234567890", "item_name": "product name", "item_variant": "variant name", "price": 100, "quantity": 1, "value": 100, "variant_currency": "INR", "variant_id": "1234567890", "variant_price": 100 } ``` #### Context [#context] | Field Name | Data Type | Description | | --- | --- | --- | | pageId | string | The identifier of the page. (Example: `productDetail`) | | product | [Product](https://shopify.dev/docs/api/storefront/2022-10/objects/Product) | A Shopify object representing a product. | | variant | [ProductVariant](https://shopify.dev/docs/api/storefront/2022-10/objects/ProductVariant) | A Shopify object representing a variant of a product. | ### `remove_from_cart` [#remove_from_cart] The `remove_from_cart` event is triggered when a product is removed from the cart. | Field Name | Data Type | Description | | ---------------- | --------- | ----------------------------------------------------------------- | | currency | string | The currency in which the item is priced. | | item_brand | string | The brand of the item. | | item_id | string | A unique identifier for the item. | | item_name | string | The name of the item. | | item_variant | string | The variant of the item, if applicable. | | price | float | The price of the item. | | quantity | integer | The number of items being purchased. | | value | float | The total value of the items being purchased (price \* quantity). | | variant_currency | string | The currency in which the variant is priced. | | variant_id | string | A unique identifier for the variant. | | variant_price | float | The price of the variant. | #### Context [#context-1] | Field Name | Data Type | Description | | --- | --- | --- | | pageId | string | The identifier of the page. (Example: `productDetail`) | | product | [Product](https://shopify.dev/docs/api/storefront/2022-10/objects/Product) | A Shopify object representing a product. | | variant | [ProductVariant](https://shopify.dev/docs/api/storefront/2022-10/objects/ProductVariant) | A Shopify object representing a variant of a product. | ### `product_viewed` [#product_viewed] The `product_viewed` event is triggered when a product is viewed. | Field Name | Data Type | Description | | ---------------- | --------- | ----------------------------------------------------------------- | | currency | string | The currency in which the item is priced. | | item_brand | string | The brand of the item. | | item_id | string | A unique identifier for the item. | | item_name | string | The name of the item. | | item_variant | string | The variant of the item, if applicable. | | price | float | The price of the item. | | quantity | integer | The number of items being purchased. | | value | float | The total value of the items being purchased (price \* quantity). | | variant_currency | string | The currency in which the variant is priced. | | variant_id | string | A unique identifier for the variant. | | variant_price | float | The price of the variant. | #### Context [#context-2] | Field Name | Data Type | Description | | --- | --- | --- | | pageId | string | The identifier of the page. (Example: `productDetail`) | | product | [Product](https://shopify.dev/docs/api/storefront/2022-10/objects/Product) | A Shopify object representing a product. | | variant | [ProductVariant](https://shopify.dev/docs/api/storefront/2022-10/objects/ProductVariant) | A Shopify object representing a variant of a product. | ### `user_login` [#user_login] The `user_login` event is triggered when a user logs in. | Field Name | Data Type | Description | | --- | --- | --- | | email | string | The email address of the user. | | id | string | The unique identifier of the user. | | method | string | The method used to log in. | | name | string | The name of the user. | | phone | string | The phone number of the user. | **_Example:_** ```json { "email": "test@gmail.com", "id": "1234567890", "method": "email", "name": "test", "phone": "1234567890" } ``` #### Context [#context-3] | Field Name | Data Type | Description | | --- | --- | --- | | customer | [Customer](https://shopify.dev/docs/api/storefront/2022-10/objects/Customer) | A Shopify object representing a customer. | ### `user_logout` [#user_logout] The `user_logout` event is triggered when a user logs out. | Field Name | Data Type | Description | | --- | --- | --- | | email | string | The email address of the user. | | id | string | The unique identifier of the user. | | name | string | The name of the user. | | phone | string | The phone number of the user. | #### Context [#context-4] | Field Name | Data Type | Description | | --- | --- | --- | | customer | [Customer](https://shopify.dev/docs/api/storefront/2022-10/objects/Customer) | A Shopify object representing a customer. | ### `user_register` [#user_register] The `user_register` event is triggered when a user registers. | Field Name | Data Type | Description | | --- | --- | --- | | email | string | The email address of the user. | | id | string | The unique identifier of the user. | | name | string | The name of the user. | | phone | string | The phone number of the user. | #### Context [#context-5] | Field Name | Data Type | Description | | --- | --- | --- | | customer | [Customer](https://shopify.dev/docs/api/storefront/2022-10/objects/Customer) | A Shopify object representing a customer. | ### `checkout_started` [#checkout_started] The `checkout_started` event is triggered when a checkout is started. | Field Name | Data Type | Description | | --- | --- | --- | | currency | string | The currency in which the item is priced. | | id | string | The unique identifier of the checkout. | | products_count | integer | The number of products in the checkout. | | total_amount | float | The total amount of the checkout. | #### Context [#context-6] | Field Name | Data Type | Description | | --- | --- | --- | | cart | [Cart](https://shopify.dev/docs/api/storefront/latest/objects/Cart) | A Shopify object representing a cart. | ### `checkout_completed` [#checkout_completed] The `checkout_completed` event is triggered when a checkout is completed. | Field Name | Data Type | Description | | --- | --- | --- | | currency | string | The currency in which the item is priced. | | id | string | The unique identifier of the checkout. | | order_id | string | The unique identifier of the order. | | order_number | integer | The number of the order. | | products_count | integer | The number of products in the checkout. | | total_amount | float | The total amount of the checkout. | #### Context [#context-7] | Field Name | Data Type | Description | | --- | --- | --- | | cart | [Cart](https://shopify.dev/docs/api/storefront/latest/objects/Cart) | A Shopify object representing a cart. | ### `view_item_list` [#view_item_list] The `view_item_list` event is triggered when a user views a list of items. | Field Name | Data Type | Description | | --- | --- | --- | | items | array | An array of items in the list. | #### Context [#context-8] No context passed ### `product_search` [#product_search] The `product_search` event is triggered when a user searches for a product. | Field Name | Data Type | Description | | --- | --- | --- | | query | string | The search query. | **_Example:_** ```json { "query": "T shirt" } ``` #### Context [#context-9] No context passed ### `cart.applycoupon` [#cartapplycoupon] The `cart.applycoupon` event is triggered when a user applies a coupon to the cart. | Field Name | Data Type | Description | | --- | --- | --- | | category | string | The category of the event. | | action | string | The action of the event. | | couponCode | string | The coupon code. | **_Example:_** ```json "category": "", "action": "APPLY_COUPON", "couponCode": "couponCodeName" ``` #### Context [#context-10] No context passed ### `product_added_to_wishlist` [#product_added_to_wishlist] The `product_added_to_wishlist` event is triggered when a product is added to the wishlist. | Field Name | Data Type | Description | | ---------------- | --------- | ----------------------------------------------------------------- | | currency | string | The currency in which the item is priced. | | item_brand | string | The brand of the item. | | item_id | string | A unique identifier for the item. | | item_name | string | The name of the item. | | item_variant | string | The variant of the item, if applicable. | | price | float | The price of the item. | | quantity | integer | The number of items being purchased. | | value | float | The total value of the items being purchased (price \* quantity). | | variant_currency | string | The currency in which the variant is priced. | | variant_id | string | A unique identifier for the variant. | | variant_price | float | The price of the variant. | **_Example:_** ```json { "item_name": "Polo para Hombre FOX CLASSIC CALIBRATED TECH TEE RDCY", "currency": "INR", "item_id": "6944079839364", "price": 87.92, "item_brand": "fox", "quantity": 1, "item_variant": "RDCY / S", "variant_price": 87.92, "value": 87.92, "variant_currency": "INR", "variant_id": "40866875801732" } ``` #### Context [#context-11] | Field Name | Data Type | Description | | --- | --- | --- | | product | [Product](https://shopify.dev/docs/api/storefront/2022-10/objects/Product) | A Shopify object representing a product. | ### `product_removed_from_wishlist` [#product_removed_from_wishlist] The `product_removed_from_wishlist` event is triggered when a product is removed from the wishlist. | Field Name | Data Type | Description | | ---------------- | --------- | ----------------------------------------------------------------- | | currency | string | The currency in which the item is priced. | | item_brand | string | The brand of the item. | | item_id | string | A unique identifier for the item. | | item_name | string | The name of the item. | | item_variant | string | The variant of the item, if applicable. | | price | float | The price of the item. | | quantity | integer | The number of items being purchased. | | value | float | The total value of the items being purchased (price \* quantity). | | variant_currency | string | The currency in which the variant is priced. | | variant_id | string | A unique identifier for the variant. | | variant_price | float | The price of the variant. | #### Context [#context-12] | Field Name | Data Type | Description | | --- | --- | --- | | product | [Product](https://shopify.dev/docs/api/storefront/2022-10/objects/Product) | A Shopify object representing a product. | ### `shareProduct` [#shareproduct] The `shareProduct` event is triggered when a user shares a product. | Field Name | Data Type | Description | | --- | --- | --- | | product_name | string | The name of the product. | #### Context [#context-13] No context passed ### `view_cart` [#view_cart] The `view_cart` event is triggered when a user views the cart. | Field Name | Data Type | Description | | --- | --- | --- | | currency | string | The currency in which the item is priced. | |id | string | A unique identifier for the item. | |total_price | float | The total price of the items in the cart. | |total_quantity | integer | The total quantity of the items in the cart. | **_Example:_** ```json { "id": "gid://shopify/Checkout/883e81276c5bb5307814a58cea91eeef?key=aecd46933486b47241453786ccdef3e9", "currency": "INR", "total_price": 285.0, "total_quantity": 2 } ``` #### Context [#context-14] | Field Name | Data Type | Description | | --- | --- | --- | |cart | [Cart](https://shopify.dev/docs/api/storefront/latest/objects/Cart) | A Shopify object representing a cart. | ### `sortApply` [#sortapply] The `sortApply` event is triggered when a user applies a sort to the list of products. | Field Name | Data Type | Description | | --- | --- | --- | | value | string | The sort applied to the list of products. | #### Context [#context-15] No context passed ### `ApplyFilter` [#applyfilter] The `ApplyFilter` event is triggered when a user applies a filter to the list of products. | Field Name | Data Type | Description | | --- | --- | --- | | action | string | The action of the event. | | filterItem | array | The filter applied to the list of products. | **_Example:_** ```json { "action": "ApplyFilter", "filterItem": [ { "available": true } ] } ``` #### Context [#context-16] No context passed ### `drawerCategoryClick` [#drawercategoryclick] The `drawerCategoryClick` event is triggered when a user clicks on a category in the drawer. | Field Name | Data Type | Description | | --- | --- | --- | | title | string | The title of the event. | | action | string | The action of the event. | **_Example:_** ```json { "title": "Collection 1-1", "action": "OPEN_COLLECTION" } ``` #### Context [#context-17] No context passed # How to edit custom events in AppsFlyer (/docs/integrations/analytics/appsflyer/custom-events) You can see the list of events sent to AppsFlyer [here](/docs/integrations/analytics/appsflyer/events) ## Steps [#steps] 1. Add this filter in the eventsHelper.js file in the your-theme/helpers/eventsHelper.js file. 2. Add the following code in the updateAppsFlyerEvents function. ```js import { appmaker } from '@appmaker-xyz/core'; function updateAppsFlyerEvents () { appmaker.addFilter( 'appsflyerEventData', 'custom-events', ({ eventName, params, eventObject }) => { console.log('eventName', eventName) switch (eventName) { case 'af_viewed_content': console.log('params', params); // params is an object object which contains the sending event attributes of the event. console.log('eventObject', eventObject); // eventObject is an object that contains whole data for the event. // example of updating the event params object using the eventObject params['Product ID'] = eventObject?.product_sku?.value; break; case 'af_add_to_cart': eventName = 'af_added_to_cart'; // example of updating the event name params['Product ID'] = eventObject?.product_sku?.value; break; default: break; } // sending the updated params and eventName return { eventName, params, }; }, ); } export { updateAppsFlyerEvents } ``` 3. call this updateAppsFlyerEvents function in the your-theme/index.js file activate. # AppsFlyer Analytics Events (/docs/integrations/analytics/appsflyer/events) | Event name | Sample event data | Description | |-------------|-------------------|-------------| | af_content_view | \{
"Product Title": "T shirt Yasi",
"af_content_id": "6793295167650",
"af_price": "32.0",
"af_currency": "INR",
"af_content_type": "T shirts",
"Total Variants": 4,
"totalInventory": 941,
"URL": 'https://cdn.shopify.com/s/files/1/0571/2193/1426/products/pexels-monstera-6311599_1_500x500.jpg?v=1655804220',
"Source": "Shopify Mobile App"
} | Opened a product | | af_add_to_cart | \{
"URL": 'https://cdn.shopify.com/s/files/1/0571/2193/1426/products/pexels-monstera-6311599_1_500x500.jpg?v=1655804220',
"Product Title": "T shirt Yasi",
"af_currency": "INR",
"af_content_id": "6793295167650",
"af_price": 15,
"af_quantity": 1,
"Source": "Shopify Mobile App",
"Variation Title": "XL / blue",
"Variation ID": "40018184732834",
"Image URL": "https://cdn.shopify.com/s/files/1/0571/2193/1426/products/pexels-monstera-6311599_1_500x500.jpg?v=1655804220",
"Vendor name": "Yasi"
} | Added to cart | | af_list_view | \{
"af_content_type": "Dresses"
} | Viewed a collection | | af_registration_method | \{
"Email": "yaseen@appmaker.xyz",
"FirstName": "john doe",
"Status": "success",
"Source": "Shopify Mobile App",
"Customer ID": "gid://shopify/Customer/5360942776482"
} | User registered | | af_login | \{
"Email": "yaseen@appmaker.xyz",
"Name": "john doe",
"id": "gid://shopify/Customer/5360942776482"
} | User logged in | | Customer Logged Out | \{} | User logged out | | View Cart | \{
"currency": 'INR',
"Total Price": 1599,
"Product quantity": 1,
"Product Price": [ '1599.0' ],
"Product ID": [ '415783236077140' ],
"Product Title": [ 'Grandiosity Camel Mustard Shirt' ],
"Variation ID": [ '41578323607714' ],
"Vendor name": [ 'appmakershopifystore' ],
"Source": "Shopify Mobile App" } | viewed cart | | af_initiated_checkout | \{
"currency": "INR",
"af_price": 1599,
"af_quantity": 1,
"Product Price": [ '1599.0' ],
"af_content_id": [ '415783236077140' ],
"Product Title": [ 'Grandiosity Camel Mustard Shirt' ],
"Variation ID": [ '41578323607714' ],
"Vendor name": [ 'appmakershopifystore' ],
"Source": 'Shopify Mobile App'
} | Started checkout process | | af_add_to_wishlist | \{
"URL": 'https://www.appmakershopifystore.co.in/products/bande-blue-shirt',
"Product Title": 'Bande Blue Shirt',
"currency": 'INR',
"Product ID": '7241159475362',
"Product Price": 699,
"Quantity": 1,
"Source": 'Shopify Mobile App',
"Image URL": 'https://cdn.shopify.com/s/files/1/0571/2193/1426/products/Blue_250x.png?v=1622623437',
"Vendor name": 'appmakershopifystore'
} | Product added to wishlist | | Removed from Cart | \{
"currency": 'INR',
"Image URL": 'https://cdn.shopify.com/s/files/1/0571/2193/1426/products/Blue_250x.png?v=1622623437',
"Product ID:: '40058478559394',
"Product Title": "Poster",
"Product Price": 555,
"Variation ID": '40058478559394',
"Variation Title": 'Blue / XL',
"Vendor name": 'Yasistores',
"Source": 'Shopify Mobile App'
} | Product removed from the cart | | af_purchase | \{
"af_order_id": '5279547588770',
"af_receipt_id": '5279547588770',
"af_currency": "INR",
"af_price": '236.0',
"af_revenue": '236.0',
"af_quantity": 1,
"af_content": 'trousers',
"af_content_list": [ "trousers" ],
"Source": 'Shopify Mobile App'
} | Item purchased | # AppsFlyer (/docs/integrations/analytics/appsflyer) # AppsFlyer One Link Configuration (/docs/integrations/analytics/appsflyer/onelink) ## Overview [#overview] This guide shows you how to configure AppsFlyer One Link. ## prerequisite [#prerequisite] Make sure you have configured deeplinking in AppsFlyer. ## Steps [#steps] 1. Go to AppsFlyer dashboard and click on **web-to-app** in the left sidebar. 2. Click on **Go to smart banner**. 3. Click on **studio**. 4. If you don't have a smart banner, create a new one. Otherwise, click on the existing smart banner. 5. Make sure both group and banner is active. 6. Click on the three dots in the top right corner of the banner and click on **get code snippet**. 7. Copy the code snippet. 8. Paste this code snippet on you global head tag in the theme. You can do this from shopify admin. Example: Go to **Online Store** > **Themes** > **Actions** > **Edit code** > **Layout** > **theme.liquid**. Paste the code snippet in the global head tag. # How to edit custom events in the CleverTap (/docs/integrations/analytics/clevertap/custom-events) ## Introduction [#introduction] This document will help you understand how to edit custom events in the CleverTap. You can see the list of events sent to clevertap [here](/docs/integrations/analytics/clevertap/events) ## Steps [#steps] 1. Add this filter in the eventsHelper.js file in the your-theme/helpers/eventsHelper.js file. 2. Add the following code in the updateCleverTapEvents function. ```js import { appmaker } from '@appmaker-xyz/core'; function updateCleverTapEvents () { appmaker.addFilter( 'cleverTapEventData', 'custom-events', ({ eventName, params, eventObject }) => { console.log('eventName', eventName) switch (eventName) { case 'Product Viewed': console.log('params', params); // params is an object object which contains the sending event attributes of the event. console.log('eventObject', eventObject); // eventObject is an object that contains whole data for the event. // example of updating the event params object using the eventObject params['Product ID'] = eventObject?.product_sku?.value; break; case 'Added to Cart': eventName = 'Add to Cart'; // example of updating the event name params['Product ID'] = eventObject?.product_sku?.value; break; case 'Added to Wishlist': params['Product ID'] = eventObject?.product_sku?.value; break; default: break; } // sending the updated params and eventName return { eventName, params, }; }, ); } export { updateCleverTapEvents } ``` 3. call this updateCleverTapEvents function in the your-theme/index.js file activate. # CleverTap Analytics Events (/docs/integrations/analytics/clevertap/events) | Sl No | Event Name | Sample Event Data | Description | |-------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| | 1 | Appmaker Block Click | \{ 'resourceUrl' : 'https://cdn.shopify.com/s/files/1/1454/5188/files/Bestsellers_New.jpg', 'block id' : 'b1fd3f08-5fb8-4524-929a-a942756ff9a7'', ParentId' : '3329cc08-71e4-4c7e-a912-13198b98913b', 'blockType' :'appmaker_banner'} | Opened a block from homepage | | 2 | drawerCategoryClick | \{ "title" : 'Hair Oil', "action" : 'OPEN_COLLECTION' } | Select category from menu | | 3 | appmaker_bottom_tab_click | \{ "tabName" : '1dd4b673-c9e1-425c-ba24-bc87857a59e0' , "tabLabel" : 'CART' , "tabPageId" : 'cartPageCheckout' } | Click on bottom bar tab | | 4 | Login | \{ 'Status' : 'success', 'Method Used' : 'email' } | Logged in | | 5 | Category Viewed | \{ 'CT Source' : 'Mobile' , 'Category Name' : 'Face Care' } | Viewed a collection | | 6 | view_item_list | \{ 'item list id' : '85337768029' , 'item_list_name' : 'Face Care' ,'item_list_handle' : 'face-care' } | Collection page is showing | | 7 | ApplyFilter | \{ 'action' : 'ApplyFilter' } | Filter | | 8 | sortApply | \{ 'value' : 'reverse: true, sortKey: PRICE', 'label' : 'Price high to low' } | Sort | | 9 | cart_created | \{ 'CheckoutId': 'gid://shopify/Checkout/16de3bd884a3f5e1564fc279498a2965?key=36623f12eee92dba272126b5b79eec2b', 'Value' : '799.0' } | When add a first product to cart | | 10 | Product Viewed | \{ 'CT Source':'Mobile' , 'Product ID' :'7263122849885', ' Product Name':'Black Tea Complex™ Hydrogel Under Eye Patches with Vegan Collagen Peptide | Anti-Ageing - 15 Pairs', ' Amount' : '499', 'totalInventory' :'-4850' } | Opened a product | | 11 | Added to Wishlist | \{ 'Product ID':'7263122849885', 'Product Name':'Black Tea Complex™ Hydrogel Under Eye Patches with Vegan Collagen Peptide | Anti-Ageing - 15 Pairs' , 'Currency' : 'INR' ,' Amount' : '499', ' totalInventory' : '-4850' } | Product added to wishlist | | 12 | product_removed_from_wishlist | \{ 'Currency' :'INR', 'Quantity':'1', 'Product Name':'2% Salicylic Acid Niacinamide & Matcha Tea Face Wash - 100 m', 'price':299, 'Variant_id': '41595662073949', 'Variant_price':'299.0', 'Variant_currency':'INR', 'Value':'299.0', 'item_brand':'App name', 'item_variant':'Default Title', 'item_id':'7283378880605' } | Product removed from wishlist | | 13 | shareProduct | \{ "product_name" : 'Black Tea Complex™ Hydrogel Under Eye Patches with Vegan Collagen Peptide | Anti-Ageing - 15 Pairs' } | Product is shared to others | | 14 | addToCart | \{ 'ProductId' :'7130788331613' , 'Currency': 'INR', 'Quantity' : '1', 'Variation ID' : '41129199534173', 'Product Price' : '1447', 'Product Title' : 'Green Tea Daily SMS Routine',' image URL' : 'https://cdn.shopify.com/s/files/img.jpg' , 'Variation Title' : 'Default Title ' , 'Source' : ' Shopify Android App' , 'Vendor name' : ' App name ' } | Added to cart | | 15 | View Cart | | Opened cart page | | 16 | cart_updated | \{ "CheckoutId" : 'gid://shopify/Checkout/16de3bd884a3f5e1564fc279498a2965?key=36623f12eee92dba272126b5b79eec2b', "Value" : '2246.0' } | Product is added or removed from cart | | 17 | Removed From Cart | \{ "Quantity" : '1', "Product ID" : '7031989338205', "Currency" : 'INR', "Source" : 'Shopify Android App' , "Vendor name" : 'App name', "Product Price" : '699', "image URL" : 'https://cdn.shopify.com/s/files/1/1454/5188/products/Group.jpg', "Variation Title" : 'Default Title', "Product Title" : 'Green Tea & 15% Vitamin C Face Serum - 30 ml', "Variation ID" : '40849521180765' } | Product deleted from cart page | | 18 | Update Cart | \{ "Source" : 'Shopify Android App' , "Vendor name" : 'App name' , "Product Price" : '499', "Product ID" : '7263122849885' , "Image URL" : 'https://cdn.shopify.com/s/files/1/1454/5188/files/Card.jpg', "Variation Title" : 'Default Title' , "Quantity" : '1' , "Product Title" : 'Black Tea Complex™ Hydrogel Under Eye Patches with Vegan Collagen Peptide | Anti-Ageing - 15 Pairs' , "currency" : 'INR' , "Variation ID" : '41506877767773' } | Product is added or removed from cart | | 19 | cartapplycoupon | \{ "couponCode" : 'PopShop_C6FzHq-50-eWFrbmlwdWx0ZUBndWZ1bS5jb20=-e', "action" : 'APPLY_COUPON', "discountValue" : '50.0' } | When apply the coupons in cart | | 20 | Checkout Begin | \{ "Total Price" : '1298' , "Price - 1" : '499', "Product Name - 1" : 'Black Tea Complex™ Hydrogel Under Eye Patches with Vegan Collagen Peptide | Anti-Ageing - 15 Pairs ' , "Quantity - 1" : '1' } | Started checkout process | | 21 | Checkout Complete | \{ "Total Price" : '399' , "Price-1" : '399' , "Product Name-1" : 'Blueberry Blast Body Wash | Fruity Blueberry Aroma - 300 ml', "Order ID" : 'gid://shopify/Order/5710589263965?key=4fbad6e3759d8d71491f6006fdfa6928' } | Item purchased | | 22 | Charged | \{ "transaction_id" : 'MCaff3766350', "total_value" : '399', "Product_id" : 'Items >> 7312589914205',"Quantity" : '1', "price" : '399' , "brand" : 'App name', "variant_id" : '41677740146781' , "variant_name" : 'Default Title' , "product_name" : 'Blueberry Blast Body Wash | Fruity Blueberry Aroma - 300 ml ' } | After purchase and showing thank you page | | 23 | Search | \{ "Keyword" : 'Green tea' } | Searching the products | | 24 | product_search_result | \{ 'item_list_name" : 'product_search_result'," item_list_id" : 'product_list ', "list_query" : 'Green tea' } | Search result page is showing | | 25 | user_logout | \{ "name " : 'Testr Test' , "id" : 'gid://shopify/Customer/5700840292445' , "email" : 'appmaker.testing1@gmail.com ' } | A user is log out from the app | # CleverTap (/docs/integrations/analytics/clevertap) #  CleverTap Apple Developer Account Configuration Doc: App Groups (/docs/integrations/analytics/clevertap/ios-app-groups) *** > ## ⚠️ IMPORTANT NOTE: Bundle Identifier Replacement [#️-important-note-bundle-identifier-replacement] > > You **must** replace all instances of the placeholder `[BUNDLE_IDENTIFIER]` with your actual, primary iOS application bundle identifier (e.g., `com.yourcompany.appname`) throughout this entire document, including in the Appmaker dashboard configuration. *** This configuration is mandatory for sharing data between your: 1. **Main App:** `[BUNDLE_IDENTIFIER]` 2. **Content Extension (Rich Push):** `[BUNDLE_IDENTIFIER].NotificationContent` 3. **Service Extension (Badge, Media):** `[BUNDLE_IDENTIFIER].NotificationService` --- ## 1. Prerequisites [#1-prerequisites] You must be logged into your Apple Developer Account with the **Account Holder** or **Admin** role. ### Required Identifier [#required-identifier] * **App Group Identifier:** `group.[BUNDLE_IDENTIFIER]` --- ## 2. Check and Create Missing Extension App IDs [#2-check-and-create-missing-extension-app-ids] You must ensure that the App IDs for your main app and both extensions are registered in the Apple Developer Portal **before** configuring capabilities. ### Targets to Check/Create: [#targets-to-checkcreate] * `[BUNDLE_IDENTIFIER].NotificationContent` (Content Extension) * `[BUNDLE_IDENTIFIER].NotificationService` (Service Extension) ### How to Check if App IDs Exist: [#how-to-check-if-app-ids-exist] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Press **CTRL+F** (or **CMD+F** on Mac) to open your browser's Find function. 3. Search for the partial identifier: `NotificationContent` or `NotificationService`. 4. If the App ID is found, you can proceed to the next section. ### Steps to Create an Extension App ID (If Missing): [#steps-to-create-an-extension-app-id-if-missing] 1. Click the **add button (+)** to register a new identifier. 2. Select **App IDs**, then click **Continue**. 3. Select type **App**, then click **Continue**. 4. **Description:** Enter a name (e.g., "CleverTap Notification Content Extension"). 5. **Bundle ID:** Select **Explicit** and enter the full identifier (e.g., `[BUNDLE_IDENTIFIER].NotificationContent`). 6. Scroll down, click **Continue**, and then **Register**. 7. **Repeat** these steps for the Service Extension App ID (`[BUNDLE_IDENTIFIER].NotificationService`). --- ## 3. Create the Shared App Group [#3-create-the-shared-app-group] An App Group provides a shared data container, enabling communication between your main app and extensions. ### Steps: [#steps] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Click the **add button (+)** to register a new identifier. 3. Select **App Groups** from the list, then click **Continue**. 4. **Description:** Enter a meaningful name (e.g., "CleverTap Shared Data Group"). 5. **Identifier:** Enter the required identifier: `group.[BUNDLE_IDENTIFIER]` 6. Click **Continue**, then **Register**. --- ## 4. Enable App Group Capability on All App IDs [#4-enable-app-group-capability-on-all-app-ids] You must enable the **App Groups** capability for the main App ID and both Extension App IDs. ### Targets to Configure (Repeat Step 4.1 for all 3 App IDs): [#targets-to-configure-repeat-step-41-for-all-3-app-ids] 1. `[BUNDLE_IDENTIFIER]` 2. `[BUNDLE_IDENTIFIER].NotificationContent` 3. `[BUNDLE_IDENTIFIER].NotificationService` ### 4.1. Configure App Groups [#41-configure-app-groups] 1. In **Certificates, IDs & Profiles**, select **Identifiers**. 2. Find and click on one of the **App IDs**. 3. Click **Edit**. 4. Check the **App Groups** box. 5. Click the **Configure** button. 6. In the list of App Groups, **check the box** next to the identifier you created: `group.[BUNDLE_IDENTIFIER]`. 7. Click **Continue** (or **Assign**), then **Save** to confirm changes to the App ID. --- ## 5. Regenerate Provisioning Profiles [#5-regenerate-provisioning-profiles] Any change to the capabilities of an App ID invalidates all associated Provisioning Profiles. These profiles must be regenerated and downloaded. ### Steps: [#steps-1] 1. In **Certificates, IDs & Profiles**, select **Profiles**. 2. Find the Provisioning Profile associated with one of your targets (it will likely show an **Invalid** status). 3. Click **Edit** on the invalid profile. 4. Click **Generate** (or **Save**) to create a new profile. 5. **Download** the new Provisioning Profile. 6. **Repeat these steps** for all other Provisioning Profiles (`Development` and `App Store`/`Ad Hoc`) associated with your **Main App** and **both Extension Targets**. --- ## 6. Appmaker Configuration Steps [#6-appmaker-configuration-steps] After completing the portal steps, configure the required settings in the Appmaker dashboard. ### 6.1 Provisioning Profile Upload (In Appmaker) [#61-provisioning-profile-upload-in-appmaker] 1. Go to the **Appmaker dashboard -> Extensions**. 2. Search for the **Provisioning Profiles extension** and **enable** it. 3. Add the following two profiles values: | Order | Field | Value | | :--- | :--- | :--- | | **First** | Bundle Identifier | `[BUNDLE_IDENTIFIER].NotificationContent` | | | Target Name | `NotificationContent` | | | Environment Variable | `CLEVERTAP_CONTENT_PROFILE` | | **Second** | Bundle Identifier | `[BUNDLE_IDENTIFIER].NotificationService` | | | Target Name | `NotificationService` | | | Environment Variable | `CLEVERTAP_SERVICE_PROFILE` | 4. After configuring both sets of values, **save** the changes. ### 6.2 Disable Firebase Notification Image [#62-disable-firebase-notification-image] If you use Firebase Analytics, disable its notification handling to avoid conflict: 1. Go to **Appmaker Dashboard -> Extensions -> Firebase Analytics**. 2. Enable the **`Disable ios notification image`** feature. 3. Click **Save**. ### 6.3 Finalizing the Build [#63-finalizing-the-build] * **Contact Appmaker support** to request regeneration of existing profiles on their system. * Once confirmation is received, you can proceed to generate successful builds with CleverTap integration. # How to add custom properties to CleverTap purchase recordPurchase function (/docs/integrations/analytics/clevertap/purchase-custom-properties) ## Steps [#steps] 1. Import appmaker from `@appmaker-xyz/core` ```js import { appmaker } from "@appmaker-xyz/core"; ``` 2. Add filter to modify the params in your theme activate function ```js appmaker.addFilter( 'clevertap-record-purchase-event-params', 'custom-events', ({ recordEventCheckoutData, recordEventCheckoutLineItems, cart }) => { console.log(cart); console.log(recordEventCheckoutData); console.log(recordEventCheckoutLineItems); recordEventCheckoutData = { ...recordEventCheckoutData, some_custom_property: 'some_custom_value', // from cart object you will get all the details }; // edit recordEventCheckoutLineItems with every item object add additonal properties recordEventCheckoutLineItems = recordEventCheckoutLineItems.map((item) => { item = { ...item, some_custom_property: 'some_custom_value', // from cart object you will get all the details }; return item; }); return { recordEventCheckoutData, recordEventCheckoutLineItems, }; }, ); ``` ## Current Default Event data [#current-default-event-data] --- **recordEventCheckoutData** ```js { "transaction_id": "order name", "total_value": 823 } ``` **recordEventCheckoutLineItems** ```js [ { "product_id": 1234, "brand": "My Brand", "product_name": "My Product Name", "variant_id": 55678, "quantity": 1, "price": 256, "variant_name": "Yellow" }, { "product_id": 4567, "brand": "My Brand", "product_name": "My Product Name", "variant_id": 67890, "quantity": 2, "price": 567, "variant_name": "Black" } ] ``` **cart** Please refer to the Shopify documentation for the cart object data https://shopify.dev/docs/api/storefront/latest/objects/Cart # Add an analytics extension in Appmaker​ (/docs/integrations/analytics/create-analytics-extension) ## Overview [#overview] This tutorial shows you how to create an analytics extension. You can use this extension to track user behavior in appmaker made apps. And also if you have to track any custom events, you can use this extension to track those events. And also this can be usefull to send targeted push notifications to your users. ## Prerequisites [#prerequisites] 1. Follow this [doc](/docs/get-started) to create a new extension 2. After creating an extension go to `packages//src/index.js`. 3. Add the following code inside the index.js file. ```js import { activateEvents } from './events'; import { configureAnalytics } from './lib'; ``` 4. Inside the activate function add the following code. ```js export function activate({settings}) { // settings is the configuration object from the appmaker dashboard if any. You can use this to configure your extension if needed. configureAnalytics(settings); // this is the function to configure your analytics library. You can use this to configure your analytics library if needed. activateEvents(settings); } ``` 5. Now go to `src/events.js` and add the following code. ```js import { shopifyIdHelper } from '@appmaker-xyz/shopify'; import { analytics } from '@appmaker-xyz/core'; import { recordEvent, analyticsSetProfile, setPageView } from './lib'; const activateEvents = (settings) => { const sendAddToCart = (params, context) => { console.log('params', params); // here you will get seggregated data for this particular event. console.log('context', context); // here you will get the whole data that will be available for this event recordEvent( 'add_to_cart', // this is the event name. You can change it according to your need. { 'Product URL': context.product.onlineStoreUrl, // In this 'Product URL' is the event attributes name which can be modified according to your need. 'Product Title': params.item_name, 'Currency': params.currency, 'Product ID': shopifyIdHelper(params.item_id, true), // shopifyIdHelper is a helper function to get the shopify id number 1234567890 from the gid://shopify/Product/1234567890 format. 'Product Price': parseInt(params.price, 10), 'Variation ID': shopifyIdHelper(params.variant_id, true), }, // these are the event properties which can be modified according to your need. context, // context should be passed as it is ); }; // Like the above function you can add more functions for other events. For example, if you want to track remove from cart event, you can add the following code. const sendRemoveFromCart = (params, context) => { recordEvent( 'remove_from_cart', { 'Product URL': context.product.onlineStoreUrl, 'Product Title': params.item_name, 'Currency': params.currency, 'Product ID': shopifyIdHelper(params.item_id, true), 'Product Price': parseInt(params.price, 10), 'Variation ID': shopifyIdHelper(params.variant_id, true), }, context, ); }; analytics.onTrack((event, params, context) => { switch (event) { case 'product_added_to_cart': sendAddToCart(params, context); break; case 'remove_from_cart': sendRemoveCart(params, context); break; // you can add more events here default: break; } }, 'your-extension-name'); analytics.onIdentify((userId, params, context) => { analyticsSetProfile(params, context); }); analytics.onPageTrack((id, name, context) => { setPageView(name) }, 'your-extension-name'); }; export { activateEvents }; ``` 6. For adding more events that are available from the app, see [Appmaker analytics events](/docs/integrations/analytics/appmaker-analytics-events). 7. create a `lib.js` file inside the `src` folder and add the following code. This is a helper file to send the data to your analytics library. ```js import { sendEventsFunction, setUserProfileFunction, setPageViewTrackFunction } from 'your-analytics-library'; // replace these with the analytics of yours and also replace the function names with the functions that you have in your analytics library. Also use the same function names in the following code. import { appmaker } from '@appmaker-xyz/core'; const recordEvent = (eventName, params, eventObject) => { const async yourExtensionData = await appmaker.applyFilters('yourExtensionNameData', { eventName, params, eventObject, }); // it is important to use this filter to get the data from the app. Then only the apps can use custom event name and event properties to the event from their theme. sendEventsFunction(yourExtensionData.eventName, yourExtensionData.params); }; const analyticsSetProfile = (params, context) => { console.log('params', params); // you will get the user details here. This will be useful to track the current user. This will be triggered when the user logs in or signs up. setUserProfileFunction(params); }; const setPageView = (pageName) => { setPageViewTrackFunction(pageName); }; const configureAnalytics = (settings) => { // configure your analytics library here }; export { recordEvent, analyticsSetProfile, setPageView, configureAnalytics, }; ``` # Firebase Analytics Automatically Tracked Events on App (/docs/integrations/analytics/firebase/automatically-tracked-events) | Event Name | Description | Parameters | | --- | --- | --- | |session_start| when a user engages the app or website. A session ID and session number are generated automatically with each session and associated with each event in the session | | | user_engagement | when the app is in the foreground or webpage is in focus for at least one second. | | | screen_view | when a screen transition occurs and any of the following criteria are met:
- No screen was previously set
- The new screen name differs from the previous screen name
- The new screen-class name differs from the previous screen-class name
- The new screen id differs from the previous screen id | firebase_screen,
firebase_screen_class,
firebase_screen_id, firebase_previous_screen,
firebase_previous_class,
firebase_previous_id,
engagement_time_msec | | app_exception | when the app crashes or throws an exception
The event is sent when you integrate Firebase Crashlytics. | fatal
timestamp
engagement_time_msec | | notification_receive | when a notification sent by FCM is received by a device when the app is in the background
Android only | message_name,
message_time,
message_device_time,
message_id,
topic,
label,
message_channel,
message_type | | notification_foreground | when a notification sent by FCM is received by a device when the app is in the foreground | message_name,
message_time,
message_device_time,
message_id,
topic,
label,
message_channel,
message_type | | notification_open | when a user opens a notification sent by FCM | message_name,
message_time,
message_device_time,
message_id,
topic,
label,
message_channel | | notification_dismiss | when a user dismisses a notification sent by Firebase Cloud Messaging (FCM)
Android only | message_name,
message_time,
message_device_time,
message_id,
topic,
label,
message_channel | | app_clear_data | when the user resets/clears the app data, removing all settings and sign-in data
Android only | | | app_remove | when an application package is removed (uninstalled) from an Android device
Android only
This event is different from the Daily uninstalls by device and Daily uninstalls by user metrics, which are both reported by Google Play Developer Console. The app_remove event counts the removal of application packages, regardless of the installation source, and the count changes depending on the date range you are using for the report. The Daily uninstalls by device and Daily uninstalls by user metrics count the removal of application packages only when they were installed from Google Play, and are reported on a daily basis.| | | app_update | when the app is updated to a new version and launched again
The previous app version id is passed as a parameter.
This event is conceptually different from the Daily upgrades by device metric, which is reported by Google Play Developer Console. An upgrade refers to the updating of the application binary, whereas an app_update event is triggered upon the subsequent launch of the upgraded app. | previous_app_version | | first_open | the first time a user launches an app after installing or re-installing it
This event is not triggered when a user downloads the app onto a device, but instead when he or she first uses it. To see raw dow/nload numbers, look in Google Play Developer Console or in iTunesConnect.
Supports measuring first_open conversions for users who accept Apple's iOS 14 app-tracking prompt.| previous_gmp_app_id,
updated_with_analytics,
previous_first_open_count,
system_app,
system_app_update,
deferred_analytics_collection,
reset_analytics_cause,
engagement_time_msec | | os_update | when the device operating system is updated to a new version. The previous operating system version id is passed as a parameter. | previous_os_version | # How to edit custom events in the Firebase (/docs/integrations/analytics/firebase/custom-events) ## Introduction [#introduction] This document will help you understand how to edit custom events in the Firebase. You can see the list of events sent to firebase [here](/docs/integrations/analytics/firebase/events) ## Steps [#steps] 1. Add this filter in the eventsHelper.js file in the your-theme/helpers/eventsHelper.js file. 2. Add the following code in the updateFirebaseEvents function. ```js import { appmaker } from '@appmaker-xyz/core'; function updateFirebaseEvents(){ appmaker.addFilter( 'firebaseEventData', 'custom-events', ({ eventName, params, eventObject }) => { switch (eventName) { case 'view_item': console.log('params', params); // params is an object object which contains the sending event attributes of the event. console.log('eventObject', eventObject); // eventObject is an object that contains whole data for the event. // example of updating the event params object using the eventObject params.items[0].item_id = eventObject?.product_sku?.value; break; case 'add_to_cart': eventName = 'Add to Cart'; // example of updating the event name params.items[0].item_id = eventObject?.product_sku?.value; break; case 'add_to_wishlist': params.items[0].item_id = eventObject?.product_sku?.value; break; default: break; } // sending the updated params and eventName return { eventName, params, }; }, ); } export { updateFirebaseEvents } ``` 3. call this updateFirebaseEvents function in the your-theme/index.js file activate. # How to see analytics events in Firebase Debug View (/docs/integrations/analytics/firebase/debug-view) It is a great tool to use when you are trying to debug your analytics implementation. ## Pre-requisites [#pre-requisites] You need to have adb installed on your machine. You can either download it from [here](https://developer.android.com/studio/releases/platform-tools) or you can try using [https://yume-chan.github.io/ya-webadb/](https://yume-chan.github.io/ya-webadb/) website to run adb commands. ## Debug View Setup [#debug-view-setup] 1. Download your Android app from Appmaker dashboard 2. Connect your device to your machine using a USB cable 3. Enable USB debugging on your device. You can find the steps [here](https://developer.android.com/studio/debug/dev-options#enable) 4. Run the following command in your terminal to check if your device is connected ```bash adb devices ``` If your device is connected, you will see the following output ```bash List of devices attached device ``` 5. Run the following command to start debug for your app. Replace `` with your app's package name. You can get the package name from appmaker dashboard. ```bash adb shell setprop debug.firebase.analytics.app ``` ![appmaker-dashboard](/docs-assets/appmaker-dashboard.png) 6. Open [console.firebase.google.com](https://console.firebase.google.com/) and navigate to your project. Click on debug view in the left sidebar. You can see your device listed in the debug view. You can also see the events that are being sent to Firebase Analytics. ![debug-view](/docs-assets/debug-view-firebase.png) 7. You can click on the events to see the parameters that are being sent to Firebase Analytics. ![debug-view](/docs-assets/debug-view-firebase-2.png) # Firebase events and parameters (/docs/integrations/analytics/firebase/events) ## Events [#events] ### `add_to_cart` [#add_to_cart] *parameters*: `value`, `currency`, `eventCategory`, `items` Inside items, there will be `item_id`, `item_name`, `price`, `item_variant`, `quantity` **Example:** ``` currency: "INR" eventCategory: "Product Screen" items: [{ item_id: "1234567890", item_name: "product name", price: 100, item_variant: "Blue / M", quantity: 1 }] ``` **It is a GA4 event.** ### `remove_from_cart` [#remove_from_cart] *parameters*: `value`, `currency`, `eventCategory`, `items` Inside items, there will be `item_id`, `item_name`, `price`, `item_variant`, `quantity` **Example:** ``` currency: "INR" eventCategory: "Cart Screen" items: [{ item_id: "1234567890", item_name: "product name", price: 100, item_variant: "Blue / M", quantity: 1 }] ``` **It is a GA4 event.** ### `view_item` [#view_item] *parameters*: `value`, `currency`, `eventCategory`, `items` Inside items, there will be `item_id`, `item_name`, `price`, `item_variant` **Example:** ``` currency: "INR" value: 100 eventCategory: "Product Screen" items: [{ item_id: "1234567890", item_name: "product name", price: 100, item_variant: "Blue / M" }] ``` **It is a GA4 event.** ### `view_item_list` [#view_item_list] *parameters*: `items` Inside items, there will be `item_id`, `item_name`, `item_variant`, `price`, `item_brand`, `quantity` **Example:** ``` items: [{ item_id: "1234567890", item_name: "product name", item_variant: "Blue / M", price: 100, item_brand: "Brand Name", quantity: 1 }] ``` **It is a GA4 event.** ### `view_cart` [#view_cart] *parameters*: `value`, `currency`, `items` Inside items, there will be `item_id`, `item_name`, `price`, `item_variant`, `quantity` **Example:** ``` currency: "INR" value: 100 items: [{ item_id: "1234567890", item_name: "product name", price: 100, item_variant: "Blue / M", quantity: 1 }] ``` **It is a GA4 event.** ### `begin_checkout` [#begin_checkout] *parameters*: `value`, `currency`, `items` Inside items, there will be `item_id`, `item_name`, `price`, `item_variant`, `quantity` **Example:** ``` currency: "INR" value: 100 items: [{ item_id: "1234567890", item_name: "product name", price: 100, item_variant: "Blue / M", quantity: 1 }] ``` **It is a GA4 event.** ### `purchase` [#purchase] *parameters*: `value`, `currency`, `transaction_id`, `userAgent`, `items` Inside items, there will be `item_id`, `item_name`, `price`, `item_variant`, `quantity` **Example:** ``` currency: "INR" value: 100 transaction_id: "1001" userAgent: "Appmaker" items: [{ item_id: "1234567890", item_name: "product name", price: 100, item_variant: "Blue / M", quantity: 1 }] ``` **It is a GA4 event.** ### `add_to_wishlist` [#add_to_wishlist] *parameters*: `value`, `currency`, `eventCategory`, `items` Inside items, there will be `item_id`, `item_name`, `price`, `quantity` **Example:** ``` currency: "INR" value: 100 eventCategory: "Product Screen" items: [{ item_id: "1234567890", item_name: "product name", price: 100, quantity: 1 }] ``` **It is a GA4 event.** ### `search` [#search] *parameters*: `search_term` **Example:** ``` "search_term": "blue shirt" ``` ### `cart_created` [#cart_created] *parameters*: `checkoutId`, `value`, `currency` Triggered when the user's cart is created for the first time (i.e. on first item added to cart). **Example:** ``` checkoutId: "abc123xyz" value: 100 currency: "INR" ``` ### `cart_updated` [#cart_updated] *parameters*: `checkoutId`, `value`, `currency` Triggered when an item is added or modified in an existing cart. **Example:** ``` checkoutId: "abc123xyz" value: 200 currency: "INR" ``` ### `user_logged_in` [#user_logged_in] *parameters*: No parameters passed ### `user_logged_out` [#user_logged_out] *parameters*: No parameters passed ### `appmaker_block_click` [#appmaker_block_click] *parameters*: `content_type`, `content_id`, `content_list_id`, `resource_url` **Example:** ```js content_type: "appmaker/banner", content_id: "b1fd3f08-5fb8-4524-929a-a942756ff9a7", content_list_id: "3329cc08-71e4-4c7e-a912-13198b98913b", resource_url: "https://cdn.shopify.com/s/files/1/banner.jpg" ``` ### `appmaker_bottom_tab_click` [#appmaker_bottom_tab_click] *parameters*: `tabName`, `tabLabel` **Example:** ```js tabName: "1dd4b673-c9e1-425c-ba24-bc87857a59e0", tabLabel: "Home" ``` ### `product_search_result` [#product_search_result] *parameters*: `item_list_name`, `list_query`, `items` Inside items, there will be `item_id`, `item_name`, `item_list_id`, `item_list_name` **Example:** ```js item_list_name: "product_search_result", list_query: "blue shirt", items: [{ item_id: "1234567890", item_name: "product name" }] ``` ### `buy_now` [#buy_now] *parameters*: `lineItem` Inside lineItem, there will be `variantId`, `quantity`, `attributes` **Example:** ```js lineItem: { variantId: "gid://shopify/ProductVariant/1234567890", quantity: 1, attributes: [] } ``` ### `RemoveFromWishlist` [#removefromwishlist] *parameters*: `eventCategory`, `eventAction`, `product_name` **Example:** ```js eventCategory: "Product Screen", eventAction: "Remove From Wishlist clicks", product_name: "product name" ``` ### `ShareProduct` [#shareproduct] *parameters*: `eventCategory`, `eventAction`, `product_name` **Example:** ```js eventCategory: "Product Screen", eventAction: "Share Product clicks", product_name: "product name" ``` ### `SortClick` [#sortclick] *parameters*: `eventCategory`, `eventAction`, `value` **Example:** ```js eventCategory: "Category Screen", eventAction: "Sort Clicks", value: "price-asc" ``` ### `FilterClick` [#filterclick] *parameters*: `eventCategory`, `eventAction`, `filter_click_item` `filter_click_item` is a JSON string truncated to 100 characters. **Example:** ```js eventCategory: "Category Screen", eventAction: "Filter Clicks", filter_click_item: "-{\"available\":true}-" ``` ### `SubCategoryClick` [#subcategoryclick] *parameters*: `eventCategory`, `eventAction`, `sub_category_name` **Example:** ```js eventCategory: "Home Screen", eventAction: "Drawer Category Clicks", sub_category_name: "Men" ``` ## App-specific events [#app-specific-events] These events are only available in apps where the relevant feature is enabled. ### `ApplyCouponCode` [#applycouponcode] *parameters*: `eventCategory`, `eventAction`, `couponCode` **Example:** ``` "eventCategory": "cart", "eventAction": "Apply Coupon Code", "couponCode": "SAVE10" ``` ## Auto-collected events [#auto-collected-events] These events are collected automatically by the Firebase SDK. | Event | Description | |---|---| | `session_start` | Triggered when a user starts a new session | | `app_remove` | Triggered when the app is uninstalled | | `screen_view` | Triggered on every screen/page change | | `user_engagement` | Triggered when the app is in the foreground | ## Shopify Checkout Sheet Kit events [#shopify-checkout-sheet-kit-events] These events are only fired when the app uses the default Shopify checkout (powered by `@shopify/checkout-sheet-kit`). They originate from Shopify's pixel events and are prefixed with `cs_` by Appmaker to identify their source. ### `cs_page_viewed` [#cs_page_viewed] *parameters*: `id`, `name`, `timestamp`, `type` ### `cs_checkout_started` [#cs_checkout_started] *parameters*: `id`, `name`, `timestamp`, `type` ### `cs_checkout_completed` [#cs_checkout_completed] *parameters*: `id`, `name`, `timestamp`, `type` # Firebase (/docs/integrations/analytics/firebase) # How to add an analytics event (/docs/integrations/analytics/how-to-add-custom-events) 1. Import the `analytics` ```js import { analytics } from "@appmaker-xyz/core"; ``` 2. Add the following code to the place where you want to track the event ```js analytics.track( "event_name", { // event properties (optional) }, { // event context (optional) } ); ``` Example: ```js analytics.track( "discount_banner_click", { discount_percentage: "50 %", }, { cart: { total: 100, currency: "EUR", lineItems: [ { name: "Product 1", quantity: 1, price: 50, currency: "EUR", }, { name: "Product 2", quantity: 1, price: 50, currency: "EUR", }, ] }, // other context properties } ); ``` # How to track page (/docs/integrations/analytics/how-to-track-page) You can use this to track the user behavior in your app. ```js import { analytics } from '@appmaker-xyz/core'; analytics.onPageTrack((id, name, context) => { if (id === 'home') { // id = 'Home Screen'; // set analytics for page viewed } }, 'your-extension-name'); ``` # Analytics (/docs/integrations/analytics) # Klaviyo Integration Documentation (/docs/integrations/analytics/klaviyo/events) This document details the events and associated attributes that are sent from the Appmaker mobile app platform (integrated with Shopify) to Klaviyo for enhanced customer engagement, analytics, and marketing automation. ## Table of Contents [#table-of-contents] 1. [Overview](#overview) 2. [E-commerce Events](#e-commerce-events) 3. [User Account Events](#user-account-events) 4. [Application Events](#application-events) 5. [Navigation and Interface Events](#navigation-and-interface-events) 6. [Additional Notes](#additional-notes) --- ## Overview [#overview] Appmaker's mobile applications track a wide range of user interactions and activities, which are relayed to Klaviyo for analysis, segmentation, and campaign automation. Events are categorized into: - E-commerce Activities - User Account Actions - Application Usage - Interface and Navigation Interactions --- ## E-commerce Events [#e-commerce-events] | Event Name | Triggered When | Attributes | |--------------------|------------------------------------------|------------| | **Added to Cart** | User adds a product to the cart | Name, currency, ProductID, Price, Quantity, Source, VariationID, Brand, ProductType, VariationTitle, ProductURL, ImageURL, Categories | | **Removed from Cart** | User removes a product from the cart | Name, currency, ProductID, Price, Quantity, Source, VariationTitle, VariationID, ImageURL, Brand | | **Update Cart** | User updates their cart | Name, currency, ProductID, Price, Quantity, Source, VariationTitle, VariationID, ImageURL, Brand | | **Added to Wishlist** | User adds a product to their wishlist | ProductURL, Name, currency, ProductID, ProductPrice, Quantity, Source, VariationTitle, VariationID, Brand | | **Removed from Wishlist** | User removes a product from their wishlist | ProductURL, Name, currency, ProductID, Price, Quantity, Source, VariationTitle, VariationID, Brand | | **Product Searched** | User searches for products | SearchString, Source | | **Category Viewed** | User views a collection | CategoryName, CategoryURL, CategoryDescription | | **Item Purchased** | User purchases an item | OrderId, OrderNumber, OrderName, ImageURL, Price, ProductID, Quantity, ProductTitle, VariationID, VariationTitle, Brand, currency, Source | | **Order Placed** | User completes an order | OrderId, OrderNumber, currency, TotalPrice, TotalItems, Price, ProductID, Quantity, Name, VariationID, Brand, ImageURL, Source | | **Checkout Started** | User initiates the checkout process | currency, TotalPrice, Item Count, ItemNames, Customer First Name, Customer Last Name, CheckoutURL, Items, Source | | **Viewed Product** | User views a product | Name, ProductID, Brand, Available, Price, TotalVariants, totalInventory, VariantTitle, VariantID, ProductURL, ImageURL, ProductType, Currency, Categories, Source | | **View Cart** | User views their cart | currency, TotalPrice, ProductQuantity, Price, ProductID, Name, VariationID, Brand, Source | | **Coupon Applied** | User applies a coupon | couponCode | --- ## User Account Events [#user-account-events] | Event Name | Triggered When | Attributes | |------------------------|-------------------------------|------------| | **Customer Registered** | User creates a new account | Email, FirstName, LastName, Phone, Status (success/failed), Source, CustomerID | | **Customer Logged In** | User logs into their account | Email, FirstName, LastName, Phone, Status (success/failed), Source, CustomerID | | **Customer Logged Out** | User logs out of their account | No attributes | --- ## Application Events [#application-events] | Event Name | Triggered When | Attributes | |--------------|-------------------------------|------------| | **Installed** | The application is installed | No attributes | | **Updated** | The application is updated | No attributes | --- ## Navigation and Interface Events [#navigation-and-interface-events] | Event Name | Triggered When | Attributes | |--------------------------|--------------------------------------------|------------| | **Filter Click** | User clicks on a filter | filter_click_item | | **Appmaker Block Clicked** | User clicks on an Appmaker block | banner_name, blockId | | **Navbar Clicks** | User toggles the drawer | category_name | | **User Icon Click** | User clicks on the user icon | No attributes | | **Sort Click** | User applies sorting on a listing | label, value | | **Share Product** | User shares a product | Name | --- ## Additional Notes [#additional-notes] This documentation is intended to help configure and understand Klaviyo event tracking integrated with Appmaker apps for Shopify. # Klaviyo (/docs/integrations/analytics/klaviyo) #  Klaviyo Apple Developer Account Configuration Doc: App Groups (/docs/integrations/analytics/klaviyo/ios-app-groups) This guide walks you through the steps on the **Apple Developer website** (`developer.apple.com`) to configure App Groups for your main iOS application and its service extension, which is necessary for Klaviyo Rich Push integration. *** > ## ⚠️ IMPORTANT NOTE: Bundle Identifier Replacement [#️-important-note-bundle-identifier-replacement] > > You **must** replace all instances of the placeholder `[BUNDLE_IDENTIFIER]` with your actual, primary iOS application bundle identifier (e.g., `com.yourcompany.appname`) throughout this entire document, including in the Appmaker dashboard configuration. *** This configuration is mandatory for sharing data between your: 1. **Main App:** `[BUNDLE_IDENTIFIER]` 2. **Service Extension:** `[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension` --- ## 1. Prerequisites [#1-prerequisites] You must be logged into your Apple Developer Account with the **Account Holder** or **Admin** role. ### Required Identifiers [#required-identifiers] * **App Group Identifier:** `group.[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension.shared` --- ## 2. Check and Create Missing Extension App ID [#2-check-and-create-missing-extension-app-id] You must ensure that the App IDs for your main app and the service extension are registered in the Apple Developer Portal **before** configuring capabilities. ### Targets to Check/Create: [#targets-to-checkcreate] * `[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension` (Service Extension) ### How to Check if App ID Exists: [#how-to-check-if-app-id-exists] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Press **CTRL+F** (or **CMD+F** on Mac) to open your browser's Find function. 3. Search for the partial identifier: `KlaviyoNotificationServiceExtension`. 4. If the App ID is found, you can proceed to the next section. ### Steps to Create the Extension App ID (If Missing): [#steps-to-create-the-extension-app-id-if-missing] 1. Click the **add button (+)** to register a new identifier. 2. Select **App IDs**, then click **Continue**. 3. Select type **App**, then click **Continue**. 4. **Description:** Enter a name (e.g., "Klaviyo Notification Service Extension"). 5. **Bundle ID:** Select **Explicit** and enter the full identifier: `[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension` 6. Scroll down, click **Continue**, and then **Register**. --- ## 3. Create the Shared App Group [#3-create-the-shared-app-group] An App Group provides a shared data container and acts as a common security boundary. ### Steps: [#steps] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Click the **add button (+)** to register a new identifier. 3. Select **App Groups** from the list, then click **Continue**. 4. **Description:** Enter a meaningful name (e.g., "Klaviyo Shared Data Group"). 5. **Identifier:** Enter the required identifier: `group.[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension.shared` 6. Click **Continue**, then **Register**. --- ## 4. Enable App Groups on All App IDs [#4-enable-app-groups-on-all-app-ids] You must enable the **App Groups** capability for the main App ID and the Extension App ID. ### Targets to Configure (Repeat Steps below for both App IDs): [#targets-to-configure-repeat-steps-below-for-both-app-ids] 1. `[BUNDLE_IDENTIFIER]` 2. `[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension` ### Configuration Steps: [#configuration-steps] 1. In **Certificates, IDs & Profiles**, select **Identifiers**. 2. Find and click on one of the **App IDs**. 3. Click **Edit**. 4. Check the **App Groups** box. 5. Click the **Configure** button. 6. In the list, **check the box** next to the identifier you created: `group.[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension.shared`. 7. Click **Continue**, then **Save** to confirm changes to the App ID. --- ## 5. Regenerate Provisioning Profiles [#5-regenerate-provisioning-profiles] Any change to the capabilities of an App ID invalidates all associated Provisioning Profiles. These profiles must be regenerated and downloaded. ### Steps: [#steps-1] 1. In **Certificates, IDs & Profiles**, select **Profiles**. 2. Find the Provisioning Profile associated with one of your targets (it will likely show an **Invalid** status). 3. Click **Edit** on the invalid profile. 4. Click **Generate** (or **Save**) to create a new profile. 5. **Download** the new Provisioning Profile. 6. **Repeat these steps** for all other Provisioning Profiles (`Development` and `App Store`/`Ad Hoc`) associated with your **Main App** and the **Service Extension Target**. --- ## 6. Appmaker Configuration Steps [#6-appmaker-configuration-steps] After completing the portal steps, configure the required settings in the Appmaker dashboard. ### 6.1 Provisioning Profile Upload (In Appmaker) [#61-provisioning-profile-upload-in-appmaker] 1. Go to the **Appmaker dashboard -> Extensions**. 2. Search for the **Provisioning Profiles extension** and **enable** it. 3. Add the following profile value: | Order | Field | Value | | :--- | :--- | :--- | | **First** | Bundle Identifier | `[BUNDLE_IDENTIFIER].KlaviyoNotificationServiceExtension` | | | Target Name | `KlaviyoNotificationServiceExtension` | | | Environment Variable | `KLAVIYO_NOTIFICATION_SERVICE_PROFILE` | 4. After configuring the value, **save** the changes. ### 6.2 Disable Firebase Notification Image [#62-disable-firebase-notification-image] If you use Firebase Analytics, disable its notification handling to avoid conflict: 1. Go to **Appmaker Dashboard -> Extensions -> Firebase Analytics**. 2. Enable the **`Disable ios notification image`** feature. 3. Click **Save**. ### 6.3 Finalizing the Build [#63-finalizing-the-build] * **Contact Appmaker support** to request regeneration of existing profiles on their system. * Once confirmation is received, you can proceed to generate successful builds with Klaviyo integration. # Meta (Facebook) (/docs/integrations/analytics/meta) # How to test Facebook (Meta) App Events (/docs/integrations/analytics/meta/test-events) {/* :::note Facebook (Meta) app events can only be tested using a **production build** of the app. Events will not be sent in development or Expo Go environments. ::: */} ## Step 0 – Sign in to Facebook account on the mobile device [#step-0--sign-in-to-facebook-account-on-the-mobile-device] 1. Install the Facebook app on the mobile device. 2. Log in using the same account that has access to the testing brand in Meta Events Manager. 3. Open the testing brand (business) in the Facebook app and keep the app running in the background. ## Step 1 – Open Meta Events Manager [#step-1--open-meta-events-manager] 1. Log in to [Meta Business](https://business.facebook.com/). 2. Open **Events Manager**. 3. From the left menu, select **Datasets**. 4. From the dataset list, select the required mobile application dataset with the correct dataset ID. 5. Open the **Test events** tab. 6. Select the channel as **App**. 7. Keep this screen open for real-time validation. ## Step 2 – Launch the mobile application [#step-2--launch-the-mobile-application] 1. Open the mobile application on the device. ## Step 3 – Perform actions in the mobile application [#step-3--perform-actions-in-the-mobile-application] Perform the following actions in the app to trigger events: - App launch - Product view - Add to cart - Add to wishlist - Checkout - Place order - Search ## Step 4 – Verify events in the Meta dashboard [#step-4--verify-events-in-the-meta-dashboard] In the **Test events** screen, verify that the following events are received: | Event | Triggered by | |---|---| | `fb_mobile_install` | App install | | `ViewContent` | Product view | | `AddToCart` | Add to cart | | `AddToWishlist` | Add to wishlist | | `InitiateCheckout` | Checkout | | `Purchase` | Place order | | `Search` | Search | ## Step 5 – Verify event parameters [#step-5--verify-event-parameters] For each received event, open the event details and verify that the required parameters are present and correct. Key parameters to check (where applicable): | Parameter | Description | |---|---| | `content_id` | Product or variant identifier | | `currency` | Currency code (e.g. `USD`, `INR`) | | `quantity` | Number of items | # How to edit custom events in the MoEngage (/docs/integrations/analytics/moengage/custom-events) ## Introduction [#introduction] This document will help you understand how to edit custom events in the MoEngage. You can see the list of events sent to MoEngage [here](/docs/integrations/analytics/moengage/events) ## Steps [#steps] 1. Add this filter in the eventsHelper.js file in the your-theme/helpers/eventsHelper.js file. ```js import { appmaker } from '@appmaker-xyz/core'; function updateMoEngageEvents () { appmaker.addFilter( 'moengageEventData', 'custom-events', ({ eventName, params, eventObject }) => { console.log('eventName', eventName) switch (eventName) { case 'Product Viewed': console.log('params', params); // params is an object object which contains the sending event attributes of the event. console.log('eventObject', eventObject); // eventObject is an object that contains whole data for the event. // example of updating the event params object using the eventObject params['Product ID'] = eventObject?.product_sku?.value; break; case 'Add To Cart': eventName = 'Add to Cart'; // example of updating the event name params['Product ID'] = eventObject?.product_sku?.value; break; default: break; } // sending the updated params and eventName return { eventName, params, }; }, ); } export { updateMoEngageEvents } ``` 2. call this updateMoEngageEvents function in the your-theme/index.js file activate. ```js import { updateMoEngageEvents } from './helpers/eventsHelper'; export default function activate() { // your other code updateMoEngageEvents(); } ``` # MoEngage Events (/docs/integrations/analytics/moengage/events) ## Product Viewed [#product-viewed] Event Name: Product Viewed | Parameter | Type | Description | | :--- | :--- | :--- | | Product Title | String | Product Title | | Product ID | String | Product ID | | Available | Boolean | Available | | Price | Number | Price | | Currency | String | Currency | | productType | String | productType | | Total Variants | Number | Total Variants | | totalInventory | Number | totalInventory | | URL | String | URL | | Source | String | Source | ## Product Searched [#product-searched] Event Name: Product Searched | Parameter | Type | Description | | :--- | :--- | :--- | | Search String | String | Search String | | Source | String | Source | ## Product Search Result [#product-search-result] Event Name: product_search_result | Parameter | Type | Description | | :--- | :--- | :--- | | item_list_id | String | item_list_id | | item_list_name | String | item_list_name | | list_query | String | list_query | ## Product Added to Cart [#product-added-to-cart] Event Name: Add To Cart | Parameter | Type | Description | | :--- | :--- | :--- | | Product URL | String | Product URL | | Product Title | String | Product Title | | currency | String | currency | | Product ID | String | Product ID | | Product Price | Number | Product Price | | Quantity | Number | Quantity | | Source | String | Source | | Variation Title | String | Variation Title | | Variation ID | String | Variation ID | | Image URL | String | Image URL | | Vendor name | String | Vendor name | ## Product Removed from Cart [#product-removed-from-cart] Event Name: Removed from Cart | Parameter | Type | Description | | :--- | :--- | :--- | | Product URL | String | Product URL | | Product Title | String | Product Title | | currency | String | currency | | Product ID | String | Product ID | | Product Price | Number | Product Price | | Quantity | Number | Quantity | | Source | String | Source | | Variation Title | String | Variation Title | | Variation ID | String | Variation ID | | Image URL | String | Image URL | | Vendor name | String | Vendor name | ## Product Updated in Cart [#product-updated-in-cart] Event Name: Update Cart | Parameter | Type | Description | | :--- | :--- | :--- | | Product URL | String | Product URL | | Product Title | String | Product Title | | currency | String | currency | | Product ID | String | Product ID | | Product Price | Number | Product Price | | Quantity | Number | Quantity | | Source | String | Source | | Variation Title | String | Variation Title | | Variation ID | String | Variation ID | | Image URL | String | Image URL | | Vendor name | String | Vendor name | ## Product Added to Wishlist [#product-added-to-wishlist] Event Name: Added to Wishlist | Parameter | Type | Description | | :--- | :--- | :--- | | Product URL | String | Product URL | | Product Title | String | Product Title | | currency | String | currency | | Product ID | String | Product ID | | Product Price | Number | Product Price | | Quantity | Number | Quantity | | Source | String | Source | | Variation Title | String | Variation Title | | Variation ID | String | Variation ID | | Vendor name | String | Vendor name | ## Product Removed from Wishlist [#product-removed-from-wishlist] Event Name: Removed from Wishlist | Parameter | Type | Description | | :--- | :--- | :--- | | Product URL | String | Product URL | | Product Title | String | Product Title | | currency | String | currency | | Product ID | String | Product ID | | Product Price | Number | Product Price | | Quantity | Number | Quantity | | Source | String | Source | | Variation Title | String | Variation Title | | Variation ID | String | Variation ID | | Vendor name | String | Vendor name | ## Cart Created [#cart-created] Event Name: cart_created | Parameter | Type | Description | | :--- | :--- | :--- | | currency | String | currency | | checkoutId | String | checkoutId | | value | Number | value | ## Cart Updated [#cart-updated] Event Name: cart_updated | Parameter | Type | Description | | :--- | :--- | :--- | | currency | String | currency | | checkoutId | String | checkoutId | | value | Number | value | ## View Cart [#view-cart] Event Name: View Cart | Parameter | Type | Description | | :--- | :--- | :--- | | currency | String | currency | | Total Price | Number | Total Price | | Product quantity | Number | Product quantity | | Product Price | Number | Product Price | | Product ID | String | Product ID | | Product Title | String | Product Title | | Variation ID | String | Variation ID | | Vendor name | String | Vendor name | | Source | String | Source | ## Checkout Started [#checkout-started] Event Name: Checkout Started | Parameter | Type | Description | | :--- | :--- | :--- | | currency | String | currency | | Total Price | Number | Total Price | | Product quantity | Number | Product quantity | | Product Price | Number | Product Price | | Product ID | String | Product ID | | Product Title | String | Product Title | | Variation ID | String | Variation ID | | Vendor name | String | Vendor name | | Source | String | Source | ## Checkout Initiated [#checkout-initiated] Event Name: Checkout Initiated | Parameter | Type | Description | | :--- | :--- | :--- | | full_name | String | full_name | | first_name | String | first_name | | email | String | email | | mobile | String | mobile | | product_titles | String | product_titles | | line_items | String | line_items | | variants | String | variants | ## Checkout Completed [#checkout-completed] Event Name: Order placed | Parameter | Type | Description | | :--- | :--- | :--- | | Order Id | String | Order Id | | Order Number | String | Order Number | | Order Name | String | Order Name | | currency | String | currency | | Total Price | Number | Total Price | | TotalItems | Number | TotalItems | | Product Price | Number | Product Price | | Product ID | String | Product ID | | Quantity | Number | Quantity | | Product Title | String | Product Title | | Variation ID | String | Variation ID | | Vendor name | String | Vendor name | | Image URL | String | Image URL | | Source | String | Source | ## Item Purchased [#item-purchased] Event Name: Item Purchased | Parameter | Type | Description | | :--- | :--- | :--- | | Order Id | String | Order Id | | Order Number | String | Order Number | | Order Name | String | Order Name | | Image URL | String | Image URL | | Product Price | Number | Product Price | | Product ID | String | Product ID | | Quantity | Number | Quantity | | Product Title | String | Product Title | | Variation ID | String | Variation ID | | Variation Title | String | Variation Title | | Vendor name | String | Vendor name | | currency | String | currency | | Source | String | Source | ## Category Viewed [#category-viewed] Event Name: Category Viewed | Parameter | Type | Description | | :--- | :--- | :--- | | Category Name | String | Category Name | ## View Item List [#view-item-list] Event Name: view_item_list | Parameter | Type | Description | | :--- | :--- | :--- | | item_list_id | String | item_list_id | | item_list_name | String | item_list_name | | item_list_handle | String | item_list_handle | ## Customer Logged In [#customer-logged-in] Event Name: Customer Logged In | Parameter | Type | Description | | :--- | :--- | :--- | | Email | String | Email | | FirstName | String | FirstName | | LastName | String | LastName | | Phone | String | Phone | | Status | String | Status | | Source | String | Source | | Customer ID | String | Customer ID | ## Customer Registered [#customer-registered] Event Name: Customer Registered | Parameter | Type | Description | | :--- | :--- | :--- | | Email | String | Email | | FirstName | String | FirstName | | LastName | String | LastName | | Phone | String | Phone | | Status | String | Status | | Source | String | Source | | Customer ID | String | Customer ID | ## Customer Logged Out [#customer-logged-out] Event Name: Customer Logged Out ## User Logout [#user-logout] Event Name: User Logout ## User Installs the App [#user-installs-the-app] Event Name: User installs the app | Parameter | Type | Description | | :--- | :--- | :--- | | Platform | String | Platform | | INSTALLED_TIME | String | INSTALLED_TIME | | VERSION | String | VERSION | | sdk_ver | String | sdk_ver | ## Appmaker Block Click [#appmaker-block-click] Event Name: appmaker_block_click | Parameter | Type | Description | | :--- | :--- | :--- | | bannername | String | bannername | | blockId | String | blockId | | resourceUrl | String | resourceUrl | | blockType | String | blockType | | parentId | String | parentId | ## Sort Click [#sort-click] Event Name: SortClick | Parameter | Type | Description | | :--- | :--- | :--- | | label | String | label | | value | String | value | ## Apply Filter [#apply-filter] Event Name: ApplyFilter | Parameter | Type | Description | | :--- | :--- | :--- | | action | String | action | | filterItem | String | filterItem | ## Share Product [#share-product] Event Name: ShareProduct | Parameter | Type | Description | | :--- | :--- | :--- | | product_name | String | product_name | ## Coupon Applied [#coupon-applied] Event Name: Coupon Applied | Parameter | Type | Description | | :--- | :--- | :--- | | couponCode | String | couponCode | # MoEngage (/docs/integrations/analytics/moengage) #  MoEngage Apple Developer Account Configuration Doc: App Groups (/docs/integrations/analytics/moengage/ios-app-groups) This guide walks you through the steps on the **Apple Developer website** (`developer.apple.com`) to configure App Groups for your main iOS application and its extensions, which is necessary for MoEngage integration. *** > ## ⚠️ IMPORTANT NOTE: Bundle Identifier Replacement [#️-important-note-bundle-identifier-replacement] > > You **must** replace all instances of the placeholder `[BUNDLE_IDENTIFIER]` with your actual, primary iOS application bundle identifier (e.g., `com.yourcompany.appname`) throughout this entire document, including in the Appmaker dashboard configuration. *** This configuration is mandatory for sharing data between your: 1. **Main App:** `[BUNDLE_IDENTIFIER]` 2. **Service Extension:** `[BUNDLE_IDENTIFIER].MoEngageExpoRichPush` 3. **Content Extension:** `[BUNDLE_IDENTIFIER].MoEngageExpoPushTemplates` --- ## 1. Prerequisites [#1-prerequisites] You must be logged into your Apple Developer Account with the **Account Holder** or **Admin** role. ### Required Identifiers [#required-identifiers] * **App Group Identifier:** `group.[BUNDLE_IDENTIFIER]` --- ## 2. Check and Create Missing Extension App IDs [#2-check-and-create-missing-extension-app-ids] You must ensure that the App IDs for your main app and both extensions are registered in the Apple Developer Portal **before** configuring capabilities. ### Targets to Check/Create: [#targets-to-checkcreate] * `[BUNDLE_IDENTIFIER].MoEngageExpoRichPush` (Service Extension) * `[BUNDLE_IDENTIFIER].MoEngageExpoPushTemplates` (Content Extension) ### How to Check if App IDs Exist: [#how-to-check-if-app-ids-exist] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Press **CTRL+F** (or **CMD+F** on Mac) to open your browser's Find function. 3. Search for the partial identifier: `MoEngageExpoRichPush` or `MoEngageExpoPushTemplates`. 4. If the App ID is found, you can proceed to the next section. ### Steps to Create an Extension App ID (If Missing): [#steps-to-create-an-extension-app-id-if-missing] 1. Click the **add button (+)** to register a new identifier. 2. Select **App IDs**, then click **Continue**. 3. Select type **App**, then click **Continue**. 4. **Description:** Enter a name (e.g., "MoEngage Rich Push Service Extension"). 5. **Bundle ID:** Select **Explicit** and enter the full identifier (e.g., `[BUNDLE_IDENTIFIER].MoEngageExpoRichPush`). 6. Scroll down, click **Continue**, and then **Register**. 7. **Repeat** these steps for the Content Extension App ID (`[BUNDLE_IDENTIFIER].MoEngageExpoPushTemplates`). --- ## 3. Create the Shared App Group [#3-create-the-shared-app-group] An App Group provides a shared data container and acts as a common security boundary. ### Steps: [#steps] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Click the **add button (+)** to register a new identifier. 3. Select **App Groups** from the list, then click **Continue**. 4. **Description:** Enter a meaningful name (e.g., "MoEngage Shared Data Group"). 5. **Identifier:** Enter the required identifier: `group.[BUNDLE_IDENTIFIER]` 6. Click **Continue**, then **Register**. --- ## 4. Enable App Groups on All App IDs [#4-enable-app-groups-on-all-app-ids] You must enable the **App Groups** capability for the main App ID and both Extension App IDs. ### Targets to Configure (Repeat Steps below for all 3 App IDs): [#targets-to-configure-repeat-steps-below-for-all-3-app-ids] 1. `[BUNDLE_IDENTIFIER]` 2. `[BUNDLE_IDENTIFIER].MoEngageExpoRichPush` 3. `[BUNDLE_IDENTIFIER].MoEngageExpoPushTemplates` ### Configuration Steps: [#configuration-steps] 1. In **Certificates, IDs & Profiles**, select **Identifiers**. 2. Find and click on one of the **App IDs**. 3. Click **Edit**. 4. Check the **App Groups** box. 5. Click the **Configure** button. 6. In the list, **check the box** next to the identifier you created: `group.[BUNDLE_IDENTIFIER]`. 7. Click **Continue**, then **Save** to confirm changes to the App ID. --- ## 5. Regenerate Provisioning Profiles [#5-regenerate-provisioning-profiles] Any change to the capabilities of an App ID invalidates all associated Provisioning Profiles. These profiles must be regenerated and downloaded. ### Steps: [#steps-1] 1. In **Certificates, IDs & Profiles**, select **Profiles**. 2. Find the Provisioning Profile associated with one of your targets (it will likely show an **Invalid** status). 3. Click **Edit** on the invalid profile. 4. Click **Generate** (or **Save**) to create a new profile. 5. **Download** the new Provisioning Profile. 6. **Repeat these steps** for all other Provisioning Profiles (`Development` and `App Store`/`Ad Hoc`) associated with your **Main App** and **both Extension Targets**. --- ## 6. Appmaker Configuration Steps [#6-appmaker-configuration-steps] After completing the portal steps, configure the required settings in the Appmaker dashboard. ### 6.1 Provisioning Profile Upload (In Appmaker) [#61-provisioning-profile-upload-in-appmaker] 1. Go to the **Appmaker dashboard -> Extensions**. 2. Search for the **Provisioning Profiles extension** and **enable** it. 3. Add the following two profiles values: | Order | Field | Value | | :--- | :--- | :--- | | **First** | Bundle Identifier | `[BUNDLE_IDENTIFIER].MoEngageExpoRichPush` | | | Target Name | `MoEngageExpoRichPush` | | | Environment Variable | `MOENGAGE_RICH_PUSH_PROFILE` | | **Second** | Bundle Identifier | `[BUNDLE_IDENTIFIER].MoEngageExpoPushTemplates` | | | Target Name | `MoEngageExpoPushTemplates` | | | Environment Variable | `MOENGAGE_PUSH_TEMPLATES_PROFILE` | 4. After configuring both sets of values, **save** the changes. ### 6.2 Disable Firebase Notification Image [#62-disable-firebase-notification-image] If you use Firebase Analytics, disable its notification handling to avoid conflict: 1. Go to **Appmaker Dashboard -> Extensions -> Firebase Analytics**. 2. Enable the **`Disable ios notification image`** feature. 3. Click **Save**. ### 6.3 Finalizing the Build [#63-finalizing-the-build] * **Contact Appmaker support** to request regeneration of existing profiles on their system. * Once confirmation is received, you can proceed to generate successful builds with MoEngage integration. # How to edit custom events in the webEngage (/docs/integrations/analytics/webengage/custom-events) ## Introduction [#introduction] This document will help you understand how to edit custom events in the webEngage. You can see the list of events sent to webEngage [here](/docs/integrations/analytics/webengage/events) ## Steps [#steps] 1. Add this filter in the eventsHelper.js file in the your-theme/helpers/eventsHelper.js file. 2. Add the following code in the updateWebEngageEvents function. ```js import { appmaker } from '@appmaker-xyz/core'; function updateWebEngageEvents(){ appmaker.addFilter( 'webengageEventData', 'custom-events', ({ eventName, params, eventObject }) => { switch (eventName) { case 'Added to Wishlist': console.log('params', params); // params is an object object which contains the sending event attributes of the event. console.log('eventObject', eventObject); // eventObject is an object that contains whole data for the event. // example of updating the event params object using the eventObject params.Title = eventObject?.product_name?.value; eventName = 'Add to Wishlist'; // changing the event name break; case 'Added to Cart': eventName = 'Add to Cart'; // example of updating the event name params.Title = eventObject?.product_name?.value; break; default: break; } // sending the updated params and eventName return { eventName, params, }; }, ); } export { updateWebEngageEvents } ``` 3. call this updateWebEngageEvents function in the your-theme/index.js file activate. ```js import { updateWebEngageEvents } from './eventsHelper'; // inside the activate function updateWebEngageEvents(); ``` # WebEngage Analytics Events (/docs/integrations/analytics/webengage/events) > ✅ **QA Verified** — Cross-checked against two production QA reports (Dec-2025 / Jan-2026, Android & iOS). Source verified against `@appmaker-packages/extension-webengage` on the `expo-53-update` branch. The verified themes use only the default events (no `webengageEventData` filter overrides). This document lists the **default** events fired by the Appmaker WebEngage plugin (`@appmaker-packages/extension-webengage`) — for each event you will find: - **What it does** — the user action it represents. - **When it is triggered** — the in-app action that fires it. - **Attributes** — the properties sent with the event. > **Scope** > - Only the default events fired from the SDK / app code are listed here. > - **Custom event overrides** added by themes/extensions via the `webengageEventData` filter are out of scope. See [How to customise WebEngage events](/docs/integrations/analytics/webengage/custom-events) to add or rename events. > - **Webhook / system events** sent to WebEngage from outside the app (Shopify webhooks like `Order Created`, `Order Updated`, `Order Cancelled`, `Checkout Updated`, `Checkout Started`, `Checkout Completed`; or WebEngage system events like `Email Sent`, `Email Delivered`, `sms send`, `Campaign Conversion`, `Push Subscribe Process`) are not fired by the plugin and are not documented here. ## Event Summary [#event-summary] | # | Event Name | What It Tracks | Triggered When | |----|---------------------------|------------------------------------------------------|--------------------------------------------------------------------| | 1 | `Product Viewed` | A product detail page (PDP) is viewed | User opens a product page | | 2 | `Category Viewed` | A collection / category page is viewed | User opens a collection / category page | | 3 | `Searched Product` | A product search is performed | User runs a search query | | 4 | `Added To Cart` | A product is added to the cart | User taps "Add to Cart" | | 5 | `Removed From Cart` | A line item is removed from the cart | User removes a line from the cart | | 6 | `Remove from Cart` | A line item's quantity is decreased | User decreases the quantity of a cart line item | | 7 | `Cart Updated` | The cart contents change | Any add / remove / update of cart contents | | 8 | `Cart Viewed` | The cart page is viewed | User opens the cart | | 9 | `Added to Wishlist` | A product is saved to wishlist | User adds a product to the wishlist | | 10 | `Offer Availed` | A coupon code is applied | User applies a coupon in the cart | | 11 | `Checkout Button Clicked` | The user starts checkout | User taps the "Checkout" button from the cart | | 12 | `Checkout Created` | A snapshot of the created checkout | Fired together with `Checkout Button Clicked` | | 13 | `Order Completed` | An order is successfully placed | Thank-you page is reached | | 14 | `Customer Registered` | A new user signs up | New user completes registration | | 15 | User Login (identity) | The user identity is attached to the WebEngage user | On user login / register — calls `webengage.user.login()` | | 16 | User Logout (identity) | The user identity is detached | On user logout — calls `webengage.user.logout()` | --- ## Product Viewed [#product-viewed] **What it does:** Marks that a product detail page (PDP) was viewed. **Triggered when:** The user lands on a product detail page. ### Attributes [#attributes] | Property | Type | Description | |------------------|---------|------------------------------------------------------| | `ID` | String | Numeric Shopify product ID | | `Price` | Number | Sale price (rounded integer) | | `Title` | String | Product name | | `Currency` | String | Currency code (e.g. `INR`, `USD`) | | `Available` | Boolean | `true` if the product is available for sale | | `Total Variants` | Number | Number of variants the product has | | `Source` | String | Online store URL of the product | | `Tags` | String | Comma-separated list of product tags | | `Image` | String | URL of the first product image | | `Variant Id` | String | Numeric Shopify variant ID | | `Discount` | Number | Discount amount (`compareAtPrice` − `price`) | --- ## Category Viewed [#category-viewed] **What it does:** Marks that a collection / category page was viewed. **Triggered when:** The user opens a collection / category page. ### Attributes [#attributes-1] | Property | Type | Description | |-----------------|--------|--------------------------------------| | `Id` | Number | Numeric Shopify collection ID | | `Title` | String | Collection / category title | | `Image` | String | Collection image URL | | `Product Count` | Number | Number of products on the page | | `Source` | String | Collection ID (string form) | --- ## Searched Product [#searched-product] **What it does:** Captures a product search. **Triggered when:** The user runs a product search. ### Attributes [#attributes-2] | Property | Type | Description | |----------|--------|----------------| | `Terms` | String | Search query | --- ## Added To Cart [#added-to-cart] **What it does:** Captures a product being added to the cart. **Triggered when:** The user taps "Add to Cart" on a product. ### Attributes [#attributes-3] | Property | Type | Description | |------------------|--------|--------------------------------------------| | `Title` | String | Product name | | `Image` | String | First product image URL | | `Vendor` | String | Product vendor | | `Quantity` | Number | Quantity added | | `Product ID` | String | Numeric Shopify product ID | | `Variant ID` | String | Numeric Shopify variant ID | | `Product Type` | String | Shopify product type | | `Variant Title` | String | Variant title (empty if `Default Title`) | | `Currency` | String | Currency code | | `Price` | Number | Unit price (rounded integer) | | `Source` | String | Online store URL of the product | --- ## Removed From Cart [#removed-from-cart] **What it does:** Captures the full removal of a line item from the cart. **Triggered when:** The user removes a line item from the cart. ### Attributes [#attributes-4] | Property | Type | Description | |------------------|--------|------------------------------------------| | `Title` | String | Product name | | `Image` | String | Variant / product image URL | | `Vendor` | String | Product vendor | | `Quantity` | Number | Quantity that was in the cart | | `Product ID` | String | Numeric Shopify product ID | | `Product Name` | String | Product name | | `Variant ID` | String | Numeric Shopify variant ID | | `Variant Title` | String | Variant title (empty if `Default Title`) | | `Product Type` | String | Shopify product type | | `Currency` | String | Currency code | | `Price` | Number | Unit price (rounded integer) | | `Source` | String | Online store URL of the product | --- ## Remove from Cart (Quantity Decrease) [#remove-from-cart-quantity-decrease] **What it does:** Captures a quantity-decrease on a cart line item. **Triggered when:** The user decreases the quantity of a cart line item. > **Note:** This is a separate event from `Removed From Cart`. The casing differs by design — it is fired on quantity decrease, not on full line removal. ### Attributes [#attributes-5] Same as [Removed From Cart](#removed-from-cart). --- ## Cart Updated [#cart-updated] **What it does:** Captures any change to the cart contents. **Triggered when:** The cart contents change (add / remove / update). ### Attributes [#attributes-6] | Property | Type | Description | |----------------------|--------|--------------------------------------------------------------| | `Line Items` | Array | Array of cart line item edges | | `Number of Products` | Number | Total quantity across all line items | | `Product Names` | String | Comma-separated list of product titles (with variant titles) | | `Total` | Number | Cart total value | --- ## Cart Viewed [#cart-viewed] **What it does:** Marks that the cart page was viewed. **Triggered when:** The user opens the cart page. ### Attributes [#attributes-7] | Property | Type | Description | |----------------------|--------|-------------------------------------------------------------| | `Line Items` | Array | Array of cart line item edges | | `Number of Products` | Number | Total quantity across all line items | | `Product Names` | String | Comma-separated list of product titles (with variant titles)| | `Total` | Number | Cart subtotal (rounded integer) | --- ## Added to Wishlist [#added-to-wishlist] **What it does:** Captures a product being saved to the wishlist. **Triggered when:** The user adds a product to the wishlist. ### Attributes [#attributes-8] | Property | Type | Description | |----------------|--------|----------------------------------------| | `Product ID` | String | Numeric Shopify product ID | | `Title` | String | Product name | | `product_name` | String | Product name (alias for compatibility) | | `Price` | Number | Product price (rounded integer) | | `currency` | String | Currency code | | `Image` | String | First product image URL | | `Vendor` | String | Product vendor | | `URL` | String | Online store URL of the variant | --- ## Offer Availed [#offer-availed] **What it does:** Captures a coupon code being applied. **Triggered when:** The user applies a coupon code in the cart. ### Attributes [#attributes-9] | Property | Type | Description | |---------------|--------|-----------------| | `Coupon Code` | String | Coupon code | --- ## Checkout Button Clicked [#checkout-button-clicked] **What it does:** Marks the start of checkout from the cart. **Triggered when:** The user taps the **Checkout** button from the cart page. ### Attributes [#attributes-10] | Property | Type | Description | |---------------|--------|-----------------------------------| | `Currency` | String | Currency code | | `Total Items` | Number | Total quantity in the cart | | `Total Price` | Number | Total cart value | --- ## Checkout Created [#checkout-created] **What it does:** Sends a richer snapshot of the checkout being created (customer + cart details). **Triggered when:** Fired together with `Checkout Button Clicked`. ### Attributes [#attributes-11] | Property | Type | Description | |-----------------------|--------|----------------------------------------------| | `Created At` | String | ISO timestamp of cart creation | | `currency` | String | Currency code | | `cart token` | String | Numeric cart ID | | `customer email` | String | Customer email (from cart) | | `customer first name` | String | Customer first name (from local user state) | | `customer last name` | String | Customer last name | | `customer phone` | String | Customer phone | | `email` | String | Customer email | | `name` | String | `firstName lastName` | | `source` | String | Cart web URL | | `subtotal price` | Number | Cart subtotal (rounded integer) | | `total price` | Number | Cart total (rounded integer) | | `total spent` | Number | Cart total (rounded integer) | | `user id` | String | Numeric customer ID | | `line_items` | Array | Array of line item edges | | `productIds` | String | Comma-separated list of product IDs | --- ## Order Completed [#order-completed] **What it does:** Captures a successful purchase. **Triggered when:** An order is successfully placed (the thank-you page is reached). ### Attributes [#attributes-12] | Property | Type | Description | |-----------------------|--------|--------------------------------------| | `Created At` | String | Cart `createdAt` timestamp | | `currency` | String | Currency code | | `customer email` | String | Customer email | | `customer first name` | String | Customer first name | | `customer id` | String | Numeric customer ID | | `customer last name` | String | Customer last name | | `customer phone` | String | Customer phone | | `email` | String | Customer email | | `name` | String | `firstName lastName` | | `phone` | String | Customer phone | | `cart token` | String | Numeric cart ID | | `checkout id` | String | Numeric checkout ID | | `checkout token` | String | Numeric checkout token | | `order number` | String | Order number | | `current total price` | Number | Order total amount | | `order id` | String | Numeric order ID | | `line_items` | Array | Array of line item edges | | `productIds` | String | Comma-separated list of product IDs | | `tags` | String | Comma-separated customer tags | | `total price` | Number | Order total | | `user_id` | String | Numeric customer ID | --- ## Customer Registered [#customer-registered] **What it does:** Captures a new user signing up. **Triggered when:** A new user completes signup. The plugin also calls `webengage.user.login()` to attach the user identity (see below). ### Attributes [#attributes-13] | Property | Type | Description | |---------------|--------|--------------------------------------| | `ID` | String | Numeric customer ID | | `Customer Id` | String | Numeric customer ID | | `Email` | String | Customer email | | `First Name` | String | Customer first name | | `Last Name` | String | Customer last name | | `Identity` | String | Customer name | | `Phone` | String | Customer phone | | `Tags` | String | Comma-separated customer tags | --- ## User Identity (Login / Logout) [#user-identity-login--logout] These are **not** `webengage.track()` events — they are calls into the WebEngage user identity API. They appear in the WebEngage QA report as **User login** / **User logout**. ### User Login [#user-login] **What it does:** Attaches the WebEngage user identity (and their email / phone attributes) to the active session. **Triggered when:** The user logs in or registers. **Behaviour:** - If the plugin setting `use_phone_as_user_id` is enabled and the user has a phone number, calls `webengage.user.login(phone)`. - Otherwise calls `webengage.user.login(email)`. - Then sets attributes: - `webengage.user.setEmail(email)` - `webengage.user.setPhone(phone)` (when phone is non-null) ### User Logout [#user-logout] **What it does:** Detaches the WebEngage user identity. **Triggered when:** The user logs out. **Behaviour:** Calls `webengage.user.logout()`. --- ## Customising or Adding Events [#customising-or-adding-events] To rename, modify, or override any of the default events listed above, use the `webengageEventData` filter from your theme or extension. See [How to customise WebEngage events](/docs/integrations/analytics/webengage/custom-events). # WebEngage (/docs/integrations/analytics/webengage) #  WebEngage Apple Developer Account Configuration Doc: App Groups & Push Notifications (/docs/integrations/analytics/webengage/ios-app-groups) This guide walks you through the steps on the **Apple Developer website** (`developer.apple.com`) to configure App Groups and Push Notifications for your main iOS application and its extensions, which is necessary for WebEngage integration. *** > ## ⚠️ IMPORTANT NOTE: Bundle Identifier Replacement [#️-important-note-bundle-identifier-replacement] > > You **must** replace all instances of the placeholder `[BUNDLE_IDENTIFIER]` with your actual, primary iOS application bundle identifier (e.g., `com.yourcompany.appname`) throughout this entire document. *** This configuration is mandatory for sharing data and enabling messaging for: 1. **Main App:** `[BUNDLE_IDENTIFIER]` 2. **Service Extension:** `[BUNDLE_IDENTIFIER].NotificationService` 3. **Content Extension:** `[BUNDLE_IDENTIFIER].NotificationViewController` --- ## 1. Prerequisites [#1-prerequisites] You must be logged into your Apple Developer Account with the **Account Holder** or **Admin** role. ### Required Identifiers [#required-identifiers] * **App Group Identifier:** `group.[BUNDLE_IDENTIFIER].WEGNotificationGroup` --- ## 2. Check and Create Missing Extension App IDs [#2-check-and-create-missing-extension-app-ids] Ensure that the App IDs for your main app and both extensions are registered in the Apple Developer Portal. ### Targets to Check/Create: [#targets-to-checkcreate] * `[BUNDLE_IDENTIFIER].NotificationService` (Service Extension) * `[BUNDLE_IDENTIFIER].NotificationViewController` (Content Extension) ### Steps to Create an Extension App ID (If Missing): [#steps-to-create-an-extension-app-id-if-missing] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Click the **add button (+)** -> Select **App IDs** -> **Continue**. 3. Select type **App** -> **Continue**. 4. **Description:** Enter a name (e.g., "WebEngage Notification Service"). 5. **Bundle ID:** Select **Explicit** and enter the full identifier (e.g., `[BUNDLE_IDENTIFIER].NotificationService`). 6. Click **Continue** -> **Register**. 7. **Repeat** for the Content Extension (`[BUNDLE_IDENTIFIER].NotificationViewController`). --- ## 3. Create the Shared App Group [#3-create-the-shared-app-group] 1. Navigate to **Certificates, IDs & Profiles** -> **Identifiers**. 2. Click the **add button (+)** -> Select **App Groups** -> **Continue**. 3. **Description:** Enter a meaningful name (e.g., "WebEngage Shared Group"). 4. **Identifier:** Enter the required identifier: `group.[BUNDLE_IDENTIFIER].WEGNotificationGroup` 5. Click **Continue** -> **Register**. --- ## 4. Enable Capabilities (App Groups & Push Notifications) [#4-enable-capabilities-app-groups--push-notifications] You must enable specific capabilities for each App ID. ### A. Configure Main App ID [#a-configure-main-app-id] **Target:** `[BUNDLE_IDENTIFIER]` 1. In **Identifiers**, click on your **Main App ID**. 2. Click **Capabilities** or **Edit**. 3. **Enable App Groups:** * Check the **App Groups** box. * Click **Configure**. * Select `group.[BUNDLE_IDENTIFIER].WEGNotificationGroup`. 4. **Enable Push Notifications:** * Scroll down and check the **Push Notifications** box. * *(Note: No extra configuration button is needed for this checkbox).* 5. Click **Save**. ### B. Configure Service Extension App ID [#b-configure-service-extension-app-id] **Target:** `[BUNDLE_IDENTIFIER].NotificationService` 1. In **Identifiers**, click on the **NotificationService** App ID. 2. Click **Capabilities** or **Edit**. 3. **Enable App Groups:** * Check the **App Groups** box. * Click **Configure**. * Select `group.[BUNDLE_IDENTIFIER].WEGNotificationGroup`. 4. Click **Save**. ### C. Configure Content Extension App ID [#c-configure-content-extension-app-id] **Target:** `[BUNDLE_IDENTIFIER].NotificationViewController` 1. In **Identifiers**, click on the **NotificationViewController** App ID. 2. Click **Capabilities** or **Edit**. 3. **Enable App Groups:** * Check the **App Groups** box. * Click **Configure**. * Select `group.[BUNDLE_IDENTIFIER].WEGNotificationGroup`. 4. Click **Save**. --- ## 5. Regenerate Provisioning Profiles [#5-regenerate-provisioning-profiles] **Crucial Step:** Changing capabilities (adding App Groups or Push) **invalidates** existing profiles. You must regenerate them. ### Steps: [#steps] 1. Navigate to **Certificates, IDs & Profiles** -> **Profiles**. 2. Locate profiles with an **Invalid** status (common after capability changes). 3. **Main App Profile:** * Click the profile -> **Edit** -> **Save** (this regenerates it). * **Download** the new profile. 4. **Extension Profiles:** * Repeat the Edit/Save/Download process for both **NotificationService** and **NotificationViewController** profiles. --- ## 6. Appmaker Configuration Steps [#6-appmaker-configuration-steps] ### 6.1 Provisioning Profile Upload [#61-provisioning-profile-upload] 1. Go to the **Appmaker dashboard -> Extensions**. 2. Search for and enable the **Provisioning Profiles extension**. 3. Upload the *newly regenerated* profiles for your extensions: | Order | Field | Value | | :--- | :--- | :--- | | **First** | Bundle Identifier | `[BUNDLE_IDENTIFIER].NotificationService` | | | Target Name | `NotificationService` | | | Environment Variable | `WEBENGAGE_SERVICE_PROFILE` | | **Second** | Bundle Identifier | `[BUNDLE_IDENTIFIER].NotificationViewController` | | | Target Name | `NotificationViewController` | | | Environment Variable | `WEBENGAGE_CONTENT_PROFILE` | 4. **Save** the changes. ### 6.2 Disable Firebase Notification Image [#62-disable-firebase-notification-image] 1. Go to **Appmaker Dashboard -> Extensions -> Firebase Analytics**. 2. Enable **`Disable ios notification image`**. 3. Click **Save**. ### 6.3 Finalizing the Build [#63-finalizing-the-build] * **Contact Appmaker support** to request regeneration of existing profiles on their system. * Once confirmed, generate a new build. # Integrations (/docs/integrations) # How to get FCM token (/docs/integrations/notifications/how-to-get-fcm-token) ## Overview [#overview] This tutorial shows you how to get the FCM token from the appmaker app. You can use this token to send push notifications to your users. ## Methods [#methods] FCM token is a unique token that is generated for each device. ```js import { onEvent } from '@appmaker-xyz/core'; ``` ```js onEvent('on_fcm_token', async (fcmToken) => { console.log("on_fcm_token", fcmToken); }); ``` ```js onEvent('on_fcm_token_change', async (fcmToken) => { console.log("on_fcm_token", fcmToken); }); ``` Any of the above events will be triggered when the FCM token is generated or changed. You can use this token to send push notifications to your users. # Push notifications (/docs/integrations/notifications) # How to Handle Notification Received and Clicked Events with Notification Payload in Plugin/Theme (/docs/integrations/notifications/notification-events) ## Description [#description] This guide explains how to handle notification events and their payloads when using react-native-firebase for notification handling. ## How to Implement in a Plugin or Theme [#how-to-implement-in-a-plugin-or-theme] 1. Inside your plugin/theme index.js file, add the following code ```js import React, { useEffect } from "react"; import messaging from "@react-native-firebase/messaging"; import { addFilter } from '@appmaker-xyz/core'; // the following function should be written outside the activate function. This function is used to handle the notification received event in app killed state. messaging().setBackgroundMessageHandler(async (remoteMessage) => { // notification received event in app killed state. }); function activate({ settings }) { // your code addFilter( "appmaker-notfication-data-with-payload", "custom-notification-data", async (notification) => { // you can handle the clicked notification here, if you want to do something on click of notification. // you can also handle the notification clicked event here. return notification; } ); } const CustomComponent = () => { useEffect(() => { messaging().onMessage(async (remoteMessage) => { // notification received event in app foreground or background state. // you can call any function here to handle the notification received event. }); }, []); return null; }; addFilter( "app-custom-root-components", "my-custom-extension-name", (currentComponents) => { currentComponents?.push(CustomComponent); return currentComponents; } ); ``` This code snippet demonstrates how to handle notification events and their payloads in a React Native app using react-native-firebase. # Reviews (/docs/integrations/reviews) # How to use Judgeme in your app - Native (/docs/integrations/reviews/judgeme-implementation-native) ## prerequisites [#prerequisites] Enable Judgeme in your app from the Appmaker dashboard. ## Rating/Review block [#ratingreview-block] This section explains how to show default rating/review view. Available blocks for reviews and ratings are: ```js { name: 'shopify/review-summery-wrapper', attributes: {}, }, { name: 'shopify/shopify-review-list-preview', attributes: {}, }, ``` - `shopify/review-summery-wrapper` - displays rating/review summary. - `shopify/shopify-review-list-preview` - displays first five reviews. ## How to use Custom View instead of default ones. [#how-to-use-custom-view-instead-of-default-ones] ### Customize review summary [#customize-review-summary] - Block `shopify/review-summery` - [Override block](/docs/build/blocks/customizing-existing-blocks) `shopify/review-summery` with your own Component. - Use hook `useReviewSummary` to retrieve all necessary data. #### Example usage: [#example-usage] ```js // Component override { name: 'shopify/review-summery', View: ReviewSummary, // The component to be rendered } // Component definition const ReviewSummary = (props) => { const { average_rating, total_questions, total_reviews, ratings, productId, openAddReview, isLoading, } = useReviewSummary(props); //.. } ``` ### Customize review list item [#customize-review-list-item] - Block `shopify/review-item` - [Override block](/docs/build/blocks/customizing-existing-blocks) `shopify/review-item` with your own Component. - Use hook `useReviewListItem` to retrieve all the necessary data from Judgeme. #### Example usage: [#example-usage-1] ```js // Override default component { name: 'shopify/review-item', View: ReviewListItem, // The component to be rendered } // Component definition const ReviewListItem = (props) => { const { body, title, reviewer, rating, imageUrls, created_at, verified } = useReviewListItem(props); //.... } ``` Customizing the review item will change the review item view in `shopify/shopify-review-list-preview` also. ### Customize Add Review Block [#customize-add-review-block] - Block `shopify/product-review-add` - [Override block](/docs/build/blocks/customizing-existing-blocks) `shopify/product-review-add` with your own Component. - Use hook `useAddReview` to retrieve all the necessary data from Judgeme. #### Example usage: [#example-usage-2] ```js const AddReview = (props) => { const { onSubmitReview, isLoading, setName, setRating, setEmail, setBody, setTitle, name, email, rating, body, title, user, } = useAddReview(props); return ( ); }; ``` # Judgeme implementation (/docs/integrations/reviews/judgeme-implementation) ## Steps to implement Judgeme in your app [#steps-to-implement-judgeme-in-your-app] - Enable Judgeme extension in appmaker dashboard - On the extension settings page enter Judgeme public token and your shop name eg: `storename.myshopify.com` - On the shopify side, make sure to make these two meta fields public. | Namespace | Key | |-----------|-----| | reviews | rating_count | | reviews | rating | - If you are using a custom theme, you can retrieve the product rating details from the hooks like [`useProductListItem`](/docs/reference/hooks/product/use-product-list-item) and [`useProductDetail`](/docs/reference/hooks/product/use-product-detail) . - To show reviews, you can use the webview with url `https://app-static-pages.appmaker.xyz/shopify/judge-me/review-detail?shop=mystore.myshopify.com&public_token=token&product_id=product_id&product_title=product_title` - To show review in a page of blocks you can add below block to show a button to open review webview. ```js { name: 'appmaker/actionbar', attributes: { title: 'Review', rightIcon: 'plus', containerStyle: { borderRadius: 0, paddingHorizontal: 10, }, appmakerAction: { action: 'OPEN_WEBVIEW', params: { url: 'https://app-static-pages.appmaker.xyz/shopify/judge-me/review-detail?shop=mystore.myshopify.com&public_token=token&product_id=product_id&product_title=product_title', }, }, }, }, ``` To show reviews natively, refer to the [judgeme native implementation](/docs/integrations/reviews/judgeme-implementation-native) # App Groups Helper (/docs/native-code/app-groups) This is useful when you need to share data between your main app and app extensions (like notification extensions, widgets, etc.). ## What are App Groups? [#what-are-app-groups] App Groups allow multiple apps or app extensions from the same developer to share data using: - Shared `UserDefaults`: `UserDefaults(suiteName: "group.identifier")` - Shared file containers - Inter-process communication ## Installation [#installation] The `withAppGroups` helper is exported from `@appmaker-xyz/expo-plugins`: ```javascript const { withAppGroups } = require('@appmaker-xyz/expo-plugins'); ``` ## Usage [#usage] ### Basic Usage (Default) [#basic-usage-default] By default, `withAppGroups` creates an app group with the identifier `group.${bundleIdentifier}`: ```javascript const { withAppGroups } = require('@appmaker-xyz/expo-plugins'); module.exports = function(config) { // Adds app groups to main app + all extension targets // Group identifier: group.com.example.myapp config = withAppGroups(config); return config; }; ``` ### Custom Suffix [#custom-suffix] You can provide a custom suffix to create a more specific app group: ```javascript const { withAppGroups } = require('@appmaker-xyz/expo-plugins'); module.exports = function(config) { // Adds app group: group.com.example.myapp.notifications config = withAppGroups(config, { groups: 'notifications' }); return config; }; ``` ### Full Custom Identifier [#full-custom-identifier] You can provide a complete app group identifier (must start with `group.`): ```javascript const { withAppGroups } = require('@appmaker-xyz/expo-plugins'); module.exports = function(config) { // Adds app group: group.custom.identifier config = withAppGroups(config, { groups: 'group.custom.identifier' }); return config; }; ``` ### Multiple App Groups [#multiple-app-groups] You can add multiple app groups by passing an array: ```javascript const { withAppGroups } = require('@appmaker-xyz/expo-plugins'); module.exports = function(config) { // Adds multiple app groups: // - group.com.example.myapp.notifications // - group.com.example.myapp.analytics // - group.custom.shared config = withAppGroups(config, { groups: ['notifications', 'analytics', 'group.custom.shared'] }); return config; }; ``` ## What Gets Modified [#what-gets-modified] The `withAppGroups` helper modifies entitlements for **all targets**: 1. **Main app** (`AppmakerRuntime.entitlements`) 2. **Notification Service Extension** (`AppmakerPushServiceExtension.entitlements`) 3. **Notification Content Extension** (`AppmakerPushContentExtension.entitlements`) All targets receive the **same app group identifiers**, allowing them to share data. ### Before [#before] ```xml aps-environment development ``` ### After [#after] ```xml aps-environment development com.apple.security.application-groups group.xyz.appmaker.runtime com.apple.security.application-groups group.xyz.appmaker.runtime ``` ## Complete Example [#complete-example] Here's a complete example of a plugin that uses app groups: ```javascript /** * Example: Analytics Plugin with App Groups * File: packages/plugins/my-analytics/app.plugin.js */ const { withAppGroups } = require('@appmaker-xyz/expo-plugins'); const withMyAnalytics = (config) => { // Add app groups for sharing analytics data between main app and extensions config = withAppGroups(config, { groups: 'analytics' }); // ... rest of your plugin configuration return config; }; module.exports = withMyAnalytics; ``` ## Using Shared Data in Swift [#using-shared-data-in-swift] Once app groups are configured, you can access shared data in your Swift code: ```swift // In your main app or extension let sharedDefaults = UserDefaults(suiteName: "group.xyz.appmaker.runtime") sharedDefaults?.set("some value", forKey: "sharedKey") // Read in another target let value = sharedDefaults?.string(forKey: "sharedKey") ``` ## Notes [#notes] - App groups are **opt-in** and not added by default - The helper automatically handles all targets (main app + extensions) - App group identifiers must match exactly across all targets - You need to configure the same app groups in Apple Developer Console and provisioning profiles - The `withAppGroups` helper only modifies entitlements files - you still need proper provisioning profiles ## Migration from Old System [#migration-from-old-system] Previously, app groups were added automatically by the `firebase-notifications` plugin. This has been changed to an opt-in system. If your plugin needs app groups: **Before:** ```javascript // App groups were added automatically ``` **After:** ```javascript const { withAppGroups } = require('@appmaker-xyz/expo-plugins'); module.exports = function(config) { config = withAppGroups(config); // ... rest of plugin return config; }; ``` ## TypeScript Support [#typescript-support] The helper includes full TypeScript type definitions: ```typescript import { withAppGroups, WithAppGroupsOptions } from '@appmaker-xyz/expo-plugins'; const options: WithAppGroupsOptions = { groups: ['notifications', 'analytics'] }; config = withAppGroups(config, options); ``` # How to add codes in your Info.plist file using expo (/docs/native-code/config-plugins/add-codes-in-info-plist) ```js const { withInfoPlist } = require('expo/config-plugins'); module.exports = function myCustomExpoFunctionName(config) { config = withInfoPlist(config, (config) => { /* Type 1 Code to add in Info.plist file (String) */ config.modResults['YourCustomMessageKey'] = 'Your custom message'; /* Type 1 Result in Info.plist file as below YourCustomMessageKey Your custom message */ /* Type 2 Code to add in Info.plist file (Dictionary) */ config.modResults.MyCustomDictionary = { MY_FIRST_KEY: 'My first value', MY_SECOND_KEY: 'My second value' }; /* Type 2 Result in Info.plist file as below MyCustomDictionary MY_FIRST_KEY My first value MY_SECOND_KEY My second value */ /* Type 3 Code to add in Info.plist file (Array) */ config.modResults.MyCustomArray = ['My first value', 'My second value']; /* Type 3 Result in Info.plist file as below MyCustomArray My first value My second value */ return config; }); return config; }; ``` # How to add codes in your MainApplication.java file using expo (/docs/native-code/config-plugins/add-codes-in-main-application-android-file) ```js const { withCustomMainApplication, } = require('@appmaker-xyz/expo-plugins'); module.exports = function myCustomExpoFunctionName(config) { config = withCustomMainApplication(config, { javaImports: [ 'com.mycustompackage.MyCustomClass', // Add your custom class package for import, If needed you can add multiple classes since this is an array. ], onCreateAfterSoLoader: 'MyCustomClass.init();', // Add your custom class initialization code here }); return config; }; ``` # How to add config plugin in project (/docs/native-code/config-plugins/add-in-project) Using expo-config-plugins , you can modify the `build.gradle` file in the android folder of the app. Learn more about [expo-config-plugins](https://docs.expo.dev/guides/config-plugins/) To add a config plugin in your project, follow the below steps: Create a file named `app.plugin.js` in the root of your project. ```js module.exports = function myCustomExpoFunctionName(config) { return config; }; ``` Add `expo_plugins` in the `package.json` file. ```json { "name": "@appmaker-packages/extension-my-custom", "version": "0.2.1", "main": "index.js", "peerDependencies": { "react-native-my-custom": "^8.7.0" }, "expo_plugins": [ "@appmaker-packages/extension-my-custom/app.plugin.js" ] } ``` # How to Add codes in IOS native files using expo in AppDelegate.m (/docs/native-code/config-plugins/adding-codes-in-appdelegate-m-file) ### Adding import statement in AppDelegate.m using expo [#adding-import-statement-in-appdelegatem-using-expo] Inside your app.plugin.js file, add the following code. ```js const { withAppDelegate } = require('expo/config-plugins'); module.exports = function myCustomExpoFunctionName(config) { config = withAppDelegate(config, (config) => { if (config.modResults.contents.includes('MyCustom/Package.h')) { return config; } const importLine = '#import '; config.modResults.contents = config.modResults.contents.replace( importLine, `${importLine} // Add your import statement here Ex: #import `, ); return config; }); return config; }; ``` ### Calling a method in AppDelegate.m using expo inside didFinishLaunchingWithOptions method [#calling-a-method-in-appdelegatem-using-expo-inside-didfinishlaunchingwithoptions-method] Inside your app.plugin.js file, add the following code. ```js const { withAppDelegate } = require('expo/config-plugins'); module.exports = function myCustomExpoFunctionName(config) { config = withAppDelegate(config, (config) => { const didFinishLaunchingWithOptionsLine = '[FIRApp configure];'; config.modResults.contents = config.modResults.contents.replace( didFinishLaunchingWithOptionsLine, `${didFinishLaunchingWithOptionsLine} // Add your method call here Ex: [self logAppLaunch]; `, ); return config; }); return config; }; ``` ### Adding a new method in AppDelegate.m using expo [#adding-a-new-method-in-appdelegatem-using-expo] Inside your app.plugin.js file, add the following code. ```js const { withAppDelegate } = require('expo/config-plugins'); module.exports = function myCustomExpoFunctionName(config) { config = withAppDelegate(config, (config) => { const newMethod = ` // Add your new method here - (void)logAppLaunch { NSLog(@"The app has launched successfully."); } `; config.modResults.contents = config.modResults.contents.replace( '@end', `${newMethod} @end`, ); return config; }); return config; }; ``` # Adding iOS Permissions with Expo Config Plugins (/docs/native-code/config-plugins/adding-ios-permissions) ## Introduction [#introduction] This guide explains how to add various iOS permissions to your Expo project using Config Plugins. By following these instructions, you can customize your app's Info.plist file to request necessary permissions from users. ## Initial Setup [#initial-setup] You could follow the steps provided in the [Bare App Config](/docs/native-code/config-plugins/bare-app-config) for a comprehensive guide to set up your project with Expo Config Plugins as the below steps only cover a small part of the process. Within your theme, create a new file named `app.plugin.js` at its root with the following structure: ```js const { withInfoPlist } = require('@expo/config-plugins'); const withIosPermissions = (config) => { return withInfoPlist(config, (config) => { // Permission keys will be added here return config; }); }; module.exports = withIosPermissions; ``` ## Common iOS Permissions [#common-ios-permissions] Here are some common iOS permissions and their corresponding `Info.plist` keys: - Photo Library: `NSPhotoLibraryUsageDescription` - Camera: `NSCameraUsageDescription` - Microphone: `NSMicrophoneUsageDescription` - Location (When In Use): `NSLocationWhenInUseUsageDescription` - Location (Always): `NSLocationAlwaysUsageDescription` - Contacts: `NSContactsUsageDescription` - Calendar: `NSCalendarsUsageDescription` - Reminders: `NSRemindersUsageDescription` - Motion & Fitness: `NSMotionUsageDescription` ## Using the Config Plugin [#using-the-config-plugin] To add permissions, modify the `withIosPermissions` function. For example, to add Photo Library and Camera permissions: ```js const withIosPermissions = (config) => { return withInfoPlist(config, (config) => { config.modResults.NSPhotoLibraryUsageDescription = 'We need access to your photos to let you choose profile pictures and share images.'; config.modResults.NSCameraUsageDescription = 'Camera access is required to take photos for your profile and to scan QR codes.'; return config; }); }; ``` You could add multiple permissions by adding more keys to the `config.modResults` object. ## Applying the Config Plugin [#applying-the-config-plugin] To use the Config Plugin in your app, add the following to your package.json: ```json { "expo_plugins": [ "@appmaker-packages/your-theme-package-name/app.plugin.js" ] } ``` This will add all the specified permissions to your Info.plist when you build your app. Remember to only include permissions that your app actually needs, as unnecessary permission requests can lead to rejection during the App Store review process. # How to add code to native using expo-bare-react-native-app (/docs/native-code/config-plugins/bare-app-config) This repository can be used to test builds and confirm that app configurations are functioning as expected. ## Get Started [#get-started] 1. Clone the `expo-bare-react-native-app` repository 2. Install all dependencies using `yarn install` 3. Add your plugin to `packages/plugins` directory 4. Create an `app.plugin.js` file at the root of your plugin with the following content: ```js module.exports = function customExportFunction(config) { return config; }; ``` 4. Update the `expo_plugins` array in `appmaker.package.plugin.json` to include the path to your plugin's `app.plugin.js` file: ```json { "expo_plugins": [ "@appmaker-xyz/plugins/my-plugin-1/app.plugin.js", "@appmaker-xyz/plugins/my-plugin-2/app.plugin.js", "@appmaker-xyz/plugins/my-plugin-2/app.plugin.js", ] } ``` 5. Run `expo prebuild` to generate platform files with your custom configuration After completing these steps, you should be able to see your custom configuration within the generated platform files. ## Configuring platform files [#configuring-platform-files] Under the hood, this is using `expo-config-plugins` to generate the paltform files. You can learn more about it [here](https://docs.expo.dev/config-plugins/introduction/) ### For Android (`build.gradle`) [#for-android-buildgradle] To add a new implementation in the `build.gradle` file, you can modify your `app.plugin.js` file as follows: ```js const { withAppBuildGradle } = require('@expo/config-plugins'); const PATH_TO_ADD = `implementation("com.facebook.react:react-android")`; const withCustomAppBuildGradleImplementation = ( config, { implementationPackage }, ) => { return withAppBuildGradle(config, (config) => { if (config.modResults.contents.includes(implementationPackage)) { return config; } config.modResults.contents = config.modResults.contents.replace( PATH_TO_ADD, `${PATH_TO_ADD} ${implementationPackage}`, ); return config; }); }; module.exports = function withCustom(config) { config = withCustomAppBuildGradleImplementation(config, { implementationPackage: 'implementation("com.custom:app-android-sdk:12.5.06")', }); return config; }; ``` #### How it works [#how-it-works] - The code first checks if the specified implementation is already present in the `build.gradle` file. - If the implementation is not found, it adds the new implementation to the file. - It uses the `withAppBuildGradle` method to modify the `build.gradle` file. - Inside the `withAppBuildGradle` method, it locates the string `implementation("com.facebook.react:react-android")` and adds the new implementation directly below it. This approach ensures that your custom implementation is added to the `build.gradle` file without duplicating existing entries, and places it in a specific location within the file. ### For iOS (`Info.plist`) [#for-ios-infoplist] To add new entries in the `Info.plist` file, you can modify your `app.plugin.js` file as follows: ```js const { withInfoPlist } = require('expo/config-plugins'); module.exports = function myCustomExpoFunctionName(config) { config = withInfoPlist(config, (config) => { // Type 1: Adding a String config.modResults['YourCustomMessageKey'] = 'Your custom message'; // Type 2: Adding a Dictionary config.modResults.MyCustomDictionary = { MY_FIRST_KEY: 'My first value', MY_SECOND_KEY: 'My second value' }; // Type 3: Adding an Array config.modResults.MyCustomArray = ['My first value', 'My second value']; return config; }); return config; }; ``` #### How it works [#how-it-works-1] - The code uses the `withInfoPlist` method from Expo's config plugins to modify the `Info.plist` file. - It demonstrates three types of modifications: adding a string, a dictionary, and an array. - For each type, it directly modifies the `config.modResults` object, which represents the contents of the `Info.plist` file. - The changes are applied without checking for existing entries, so be cautious to avoid overwriting important existing configurations. ### Modifying `MainApplication.java` and `AppDelegate.m` [#modifying-mainapplicationjava-and-appdelegatem] You can find the guides for injecting code into [`AppDelegate.m`](/docs/native-code/config-plugins/adding-codes-in-appdelegate-m-file) and [`MainApplication.java`](/docs/native-code/config-plugins/add-codes-in-main-application-android-file). # Config plugins (/docs/native-code/config-plugins) # How to modify build.gradle file (/docs/native-code/config-plugins/modify-build-gradle) in your `app.plugin.js` file, you can write below to add new implementation in `build.gradle` file. ```js const { withAppBuildGradle } = require('@expo/config-plugins'); const PATH_TO_ADD = `implementation("com.facebook.react:react-android")`; const withCustomAppBuildGradleImplementation = ( config, { implementationPackage }, ) => { return withAppBuildGradle(config, (config) => { if (config.modResults.contents.includes(implementationPackage)) { return config; } config.modResults.contents = config.modResults.contents.replace( PATH_TO_ADD, `${PATH_TO_ADD} ${implementationPackage}`, ); return config; }); }; module.exports = function withCustom(config) { config = withCustomAppBuildGradleImplementation(config, { implementationPackage: 'implementation("com.custom:app-android-sdk:12.5.06")', }); return config; }; ``` In the above code, we are adding a new implementation in the `build.gradle` file. How it works is, it first checks if the implementation is already added in the file. If it is not added, then it adds the implementation in the file. using the `withAppBuildGradle` method. inside `withAppBuildGradle` method, we are finding the the string `implementation("com.facebook.react:react-android")` and adding the new implementation below it. # Sample expo plugin file for iOS and native changes (/docs/native-code/config-plugins/sample-expo-plugin-file) So for best practice, you can create a new file named `app.plugin.js` in the root of your project and add the following code. Also as a best practice, you can add your custom codes in separate functions for iOS and Android and if you can keep these functions in separate files and import them in `app.plugin.js` file for better code management. ## app.plugin.js [#apppluginjs] ```js const { withAppDelegate, withInfoPlist, withAppBuildGradle } = require('expo/config-plugins'); const applyIOS = (config) => { config = withAppDelegate(config, (config) => { // Add your custom codes here return config; }); config = withInfoPlist(config, (config) => { // Add your custom code here return config; }); return config; }; const applyAndroid = (config) => { config = withAppBuildGradle(config, (config) => { // Add your custom code here return config; }); return config; }; module.exports = function myCustomExpoFunctionName(config) { config = applyIOS(config); config = applyAndroid(config); return config; }; ``` ## Best practices [#best-practices] 1. Do not put console.log in the plugin file when you are building the app for production. It might fail the build process. But you can use console.log for debugging purposes. 2. Keeping android and iOS codes in separate functions and separate files for better code management. `app.plugin.js` ```js const { applyIos } = require('./buildConfig/ios'); const { applyAndroid } = require('./buildConfig/android'); module.exports = function myCustomExpoFunctionName(config) { config = applyIOS(config); config = applyAndroid(config); return config; }; ``` `buildConfig/ios.js` ```js const { withAppDelegate, withInfoPlist } = require('expo/config-plugins'); module.exports.applyIos = function applyIos(config) { config = withAppDelegate(config, (config) => { // Add your custom codes here return config; }); config = withInfoPlist(config, (config) => { // Add your custom code here return config; }); return config; }; ``` `buildConfig/android.js` ```js const { withAppBuildGradle } = require('expo/config-plugins'); module.exports.applyAndroid = function applyAndroid(config) { config = withAppBuildGradle(config, (config) => { // Add your custom code here return config; }); return config; }; ``` # How to add permissions on app (/docs/native-code/how-to-add-permissions-on-app) ## Introduction [#introduction] In this guide, we will learn how to add permissions on the app. We will use the `app-permissions` plugin to add permissions on the app. ## How to add permissions on the app [#how-to-add-permissions-on-the-app] Below is an example on adding permissions for location and camera on the app. It will request for the permissions when the app is opened since we are adding in root component. Similarly, you can add the permissions code in any component where you want to request for the permissions. It can be added in the useEffect hook of the component. You can add any number of permissions in the `permissions` array. ```jsx import React, { useEffect } from "react"; import { PERMISSIONS , requestMultiple } from "react-native-permissions"; import { appPluginStoreApi } from "@appmaker-xyz/core"; import { Platform } from "react-native"; const checkPermission = async (permission, permissions) => { if (permissions && permissions.length > 0) { const permissionIndex = permissions.findIndex( (p) => p.permission === permission ); if (permissionIndex !== -1) { return true; } } return false; } const CustomComponent = () => { useEffect(() => { const permissions = appPluginStoreApi()?.getState()?.plugins?.["app-permissions"]?.settings ?.permissions; const platformPermissions = []; // permissions = [{permission: "location"}, {permission: "camera"}] if(checkPermission('camera', permissions)){ if (Platform.OS === "ios") { platformPermissions.push(PERMISSIONS.IOS.LOCATION_WHEN_IN_USE); } else { platformPermissions.push(PERMISSIONS.ANDROID.ACCESS_FINE_LOCATION); } } requestMultiple(platformPermissions) .then((statuses) => { console.log("permissions", statuses); }) .catch((err) => { console.log("permissions->error", err); }); }, []); return null; }; addFilter("app-custom-root-components", "test-case", (currentComponents) => { currentComponents?.push(CustomComponent); return currentComponents; }); // whole code should be placed outside activate function function activate() { console.log("Activated"); } ``` In the above code, we are adding the `CustomComponent` in the root component. We are checking if the permissions are added in the `app-permissions` plugin settings. If the permissions are added, we are requesting for the permissions. # Native code (/docs/native-code) # Instructions for adding libraries that contain native code (/docs/native-code/instructions-for-adding-libraries) ## Description [#description] This guide will help you to add libraries that contain native code to your app. ## Steps [#steps] 1. Open the theme or extension's `package.json` file. 2. Add the native dependencies required inside the peer-dependencies section. Below is an example of how to add the `react-native-webview` library. ```json { "name": "@appmaker-packages/sample-theme", "peerDependencies": { "react-native-webview": "12.2.0" } } ``` Likewise, you can add other libraries as well. 3. Save the changes to the package.json file. 4. Run the command `appmaker release` to release your extension or theme. 5. Access the partner dashboard. 6. Navigate to the **App Builds** section. 7. Select the "debug" option for the build types. For more information on app builds section, refer to the [App Builds](/docs/partner-dashboard/app-build) guide. 8. Initiate the debug build process from the partner dashboard. Please follow these steps to add the necessary native dependencies and perform the appmaker release, followed by a debug build from the partner dashboard. # App build Trigger (/docs/partner-dashboard/app-build-trigger) Once a build is created you can view the same on the build list with all the details that were entered while configuring. ## Configuration [#configuration] To access the App build trigger section, navigate to `App builds` within the Appmaker dashboard (as shown in the screenshot below) ![Configuration](/docs-assets/app-build/step-1.png) Once within the `App builds` tab, you can create new test builds by selecting the relevant options for your build. (Refer to screenshot 2) ![dashboard](/docs-assets/app-build/step-2.png) ### **Section 1 ** [#section-1-] **`Build name`** - Enter a name for your build under the “build name” input. **`Appmaker SDK name`** - Enter the appmaker sdk name. for eg:stable. **`Appmaker SDK version`** - Enter the appmaker sdk version. **`Build type`** - For iOS, from the drop-down menu, select either preview or release or developement. > (Note: For uploading the build to the test flight - please ensure to select “release”). **`Platform`** - Select either `android`or `iOS` from the multi-select input. ### **Section 2** [#section-2] `Packages` - Click on the “**`+New`**” button in the packages section. From the expanded window, Provide package name and version number ### **Section 3 ** [#section-3-] * * * Enable **Auto refresh** option to auto refresh the page ### **Create build**: [#create-build] Click on “`Create build`” to create your test build. {/* ![Group 4 (36).png](/img/app-builld/group%204%20(36).png) */} {/* ![Group 3 (35).png](/img/app-builld/group%203%20(35).png) */} ## **Download Build** [#download-build] ![Download](/docs-assets/app-build/step-3.png) **Once a build is created you can view the same on the build list with all the details that were entered while configuring**. 5. **Build Type** - Build type shows the type of build selected during the configuration. 6. **Status** - Status shows the status of the build. There are 3 statuses that display the progress. - `In Progress` - `Failed ` - `Success` 7. **Download** - The green download icon allows you to download the .zip file or .apk file based on the platform that was selected. 8. **Download using the QR Code** - This option allows you to scan the QR code directly from your mobile phone. 9. **Refresh** - The refresh button allows you to refresh the build if the status remains the same. # App Build (/docs/partner-dashboard/app-build) ## Configuration [#configuration] ### Step 1 - Navigate to the App Build page [#step-1---navigate-to-the-app-build-page] To access the App Build page, navigate to the [Appmaker partner dashboard](https://partners.appmaker.xyz/). Once logged in, you will be taken to the homepage of the partner dashboard. Click on the "`App Build`" menu to access the App Build page. ### Step 2 - Create a new build [#step-2---create-a-new-build] Enter the following details to create a new build: - `Name` - Provide a name for the App build. - `project` - Select the relevant project for which the build is being created. - `Appmaker Sdk Name` - expo-v2-53-26-05 - `Appmaker Sdk Version` - latest - `Platform` - Select the platform for which the build is being created. You can select from the following options: - `Android` - The build will be created for Android. - `iOS` - The build will be created for iOS. - `Type` - Select the type from the drop down menu. You can select from the following options: - `Release` - The build will be created for release. - `Development` - The build will be created for debug. - `Package releases` - Select the package version from the drop down menu. If the project you want to take build for is not listed in the drop down of the `project` field, you can send a [**project access request**](/docs/partner-dashboard/request-project-access) to the merchant and once the merchant [**approves the request**](https://docs.appmaker.xyz/docs/MISC/project-permissions), you will be able to see the project in the drop down. You can check the below example screenshot for reference: Once the required details are entered, click on the "`Create App Build`" button to create a new build. The status bar on the right side will display the progress of the buld. ### Step 3 - Download the build [#step-3---download-the-build] Once the build status changes to completed, you can download the build by clicking on the "`Download Apk`" button. # How to debug IOS on simulator (/docs/partner-dashboard/app-debug-build-ios) ## Step 1 [#step-1] 1. Go to appmaker dashboard and click on the `App Builds` tab. 2. Make sure you select the `IOS` platform while creating the build and the type of build as `Development`. For remaning sections refer [App builds](/docs/partner-dashboard/app-build) doc. Select the `IOS` platform while creating the build and also select the type of build as `Development`. 3. After the build is created, click on the `Download IPA` button to download the build. 4. After the build is downloaded, unzip the build and open the simulator. 5. Drag and drop the build into the simulator.