Supporting Multiple Google Tag Manager Containers

When working on an iOS app that utilizes Google Tag Manager (GTM), you might encounter a scenario where you need different GTM containers for different build configurations (e.g., Debug and Release). Unfortunately this scenario isn't directly supported by Google, so we need ot come up with our own solution. A practical approach is to dynamically copy the appropriate GTM container JSON file into your app bundle based on the build configuration. This article outlines how to accomplish this with a build script.

Setting Up GTM Container Files

Start by placing your GTM container JSON files in a designated folder inside your project directory. For example:

<Project Root>
    ├── GTM/
    │   ├── GTM-AAAAAAAA.json  # Test Container
    │   ├── GTM-BBBBBBBB.json  # Live Container
    ├── YourApp/

Creating the Copy Script

The following shell script will be responsible for copying the correct GTM container file to a container subfolder in the app bundle during the build process. You can either paste it directly into the Run Script phase in Xcode or save it as a separate shell script file and reference it from the Run Script phase. I would suggest the latter approach for better maintainability.

# Names of source resource files
FOLDER_PATH=${PROJECT_DIR}/GTM
GTM_CONTAINER_TEST=GTM-AAAAAAAA.json
GTM_CONTAINER_LIVE=GTM-BBBBBBBB.json

# Destination location for the GTM container file
GOOGLE_DESTINATION=${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/container

if [ "${CONFIGURATION}" == "Release" ]; then
  GOOGLE_SRC="${GTM_CONTAINER_LIVE}"
else
  GOOGLE_SRC="${GTM_CONTAINER_TEST}"
fi
GTM_SRC_PATH="${FOLDER_PATH}/$GOOGLE_SRC"

echo "SOURCE FILE: ${GOOGLE_SRC}"
echo "CONFIG: ${CONFIGURATION}"

if [ ! -f "$GTM_SRC_PATH" ]; then
  echo "Missing 'GTM Container' source at '${GTM_SRC_PATH}'"
  exit 1
fi
mkdir -p "${GOOGLE_DESTINATION}" # Create `container` folder before copying json file
cp "${GTM_SRC_PATH}" "${GOOGLE_DESTINATION}/${GOOGLE_SRC}"

Explanation of the Script

• It determines the appropriate GTM container JSON file based on the build configuration.

• It sets the destination directory where the GTM container will be copied.

• If the required GTM container file is missing, the script fails with an error message.

• It creates the container folder (if it doesn't exist) inside the app bundle.

• It copies the correct GTM container JSON file to the designated location inside the app bundle.

Integrating the Script into the Xcode Build Process

To automate this process, follow these steps:

• Open Xcode and select your project in the Project Navigator.

• Navigate to the Build Phases tab.

• Click the + button and select New Run Script Phase.

• Drag the new phase above Compile Sources.

• Expand the phase and paste the copy script into the script editor.

• Click Close to save your changes.

Verifying the Setup

After adding the script, build the app in different configurations and verify that the correct GTM container JSON file is being copied. You can do this by checking the build logs for the generated output by the script.

For a Debug build:

SOURCE FILE: GTM-AAAAAAAA.json
CONFIG: Debug

For a Release build:

SOURCE FILE: GTM-BBBBBBBB.json
CONFIG: Release

When running the app, GTM will also print the found container name into Xcode's console. Or an error like

Conclusion

By utilizing a build script, you ensure that the correct GTM container is always included in the app bundle based on the build configuration. This approach streamlines the development and deployment process, reducing the risk of manually copying incorrect files.

Happy coding!