This guide provides a step-by-step guide on how to create a private, versioned Git repository to automate the management and distribution of the HERE SDK for both Flutter and native iOS development.

Managing large binary dependencies like the HERE SDK in a team environment can be challenging. This guide presents a robust, automated solution using a private Git repository as a package source. This approach simplifies the developer workflow, ensures version consistency, and integrates seamlessly with CI/CD pipelines and native dependency management tools.

Prerequisites

Before you begin, ensure you have the following:

1) A private Git repository (e.g., on GitHub, GitLab, Bitbucket).

2) Git LFS (Large File Storage) initialized in your repository to handle large binary files efficiently.

3) Your HERE SDK credentials (API Key).

4) A CI/CD environment (e.g., Jenkins, GitHub Actions) where the automation script can be executed.

1. Method for Flutter

This method uses a private Git repository to host the unpacked HERE SDK Flutter plugin. Your project's pubspec.yaml will then reference the SDK directly from this repository. To maintain multiple versions, we will store each SDK version in a separate directory.

Step 1: The Automation Script

This script downloads a specific version of the HERE SDK, unpacks it into a versioned directory within your private Git repository, and pushes the changes. It is designed to be run in your CI/CD environment.

#!/usr/bin/env bash
set -euo pipefail

# === CONFIGURATION (set in your CI environment) ===
HERE_API_KEY="${HERE_API_KEY:?must be set}"
SDK_VERSION="${SDK_VERSION:-4.22.5.0.197265}" # The SDK version to sync
HERE_SDK_FLUTTER_PACKAGES_REPO="git@your-git-server:here_sdk_flutter_packages.git"
CLONE_DIR="here_sdk_flutter_packages"

# We create the directory for the specific version
VERSION_PATH="versions/${SDK_VERSION}"

# --- SDK Download URL Construction ---
MAJOR_VERSION=$(echo $SDK_VERSION | cut -d. -f1-4)
ZIP_NAME="heresdk-navigate-flutter-${SDK_VERSION}.zip"
DOWNLOAD_URL="https://artifact.api.platform.here.com/v1/references/hrn:here:artifact::olp-here:com.here.sdk:heresdk-navigate-flutter:${MAJOR_VERSION}/${ZIP_NAME}?apiKey=${HERE_API_KEY}"

echo "→ Cloning Flutter SDK packages repo…"
rm -rf "${CLONE_DIR}"
git clone "${HERE_SDK_FLUTTER_PACKAGES_REPO}" "${CLONE_DIR}"
cd "${CLONE_DIR}"

echo "→ Downloading HERE SDK v${SDK_VERSION}…"
curl -fSL "${DOWNLOAD_URL}" -o "../${ZIP_NAME}"

echo "→ Cleaning old files for this version (if any)..."
rm -rf "${VERSION_PATH}"

echo "→ Creating target directory: ${VERSION_PATH}"
mkdir -p "${VERSION_PATH}"

echo "→ Unzipping SDK into ${VERSION_PATH}…"
# The SDK zip contains a 'here-sdk-flutter' directory, we unzip its contents
unzip -q "../${ZIP_NAME}" "here-sdk-flutter/*" -d "${VERSION_PATH}"
mv "${VERSION_PATH}/here-sdk-flutter" "${VERSION_PATH}/here_sdk" # Rename for consistency
rm "../${ZIP_NAME}"

echo "→ Committing & tagging v${SDK_VERSION}…"
git add .
git commit -m "Sync HERE SDK for Flutter ${SDK_VERSION}"
git tag "flutter-v${SDK_VERSION}"
git push origin main --tags

echo "HERE SDK for Flutter v${SDK_VERSION} mirrored successfully."

Step 2: Update Your `pubspec.yaml`

To use a specific version of the SDK from your repository, update the dependencies section in your Flutter project's pubspec.yaml file.

<br />dependencies: here_sdk: git: url: git@your-git-server:here_sdk_flutter_packages.git # Use the specific version tag created by the script ref: flutter-v4.22.5.0.197265 # Path to the specific version's plugin directory path: versions/4.22.5.0.197265/here_sdk<br />

### 2. Method for iOS (Swift Package Manager)

This method turns your private Git repository into a Swift Package source. Xcode can then fetch and integrate the HERE SDK directly, with versioning managed by Git tags. While the main branch will always point to the latest synced version, previous versions remain accessible via their tags.

Step 1: Make the Private Repo SPM-Compatible (One-Time Setup)

Clone your empty private repository for the iOS SDK.
In the root of the repository, create a file named Package.swift.
Paste the following code into the file. This manifest tells SPM that the package provides the HERESDK binary framework.

// swift-tools-version:6.0
import PackageDescription

let package = Package(
    name: "HERESDK",
    platforms: [
        .iOS(.v15) // Specify the minimum iOS version the app supports
    ],
    products: [
        .library(
            name: "HERESDK",
            targets: ["HERESDK"])
    ],
    targets: [
        .binaryTarget(
            name: "HERESDK",
            path: "./HERESDK.xcframework" // Tells SPM where to find the framework
        )
    ]
)

Commit and push this Package.swift file.

Step 2: The Automation Script

This script downloads the specified iOS SDK, unpacks the .xcframework, places it at the root of the repository, and creates a version tag.

#!/usr/bin/env bash
set -euo pipefail

# === CONFIGURATION (set in your CI environment) ===
HERE_API_KEY="${HERE_API_KEY:?must be set in CI vars}"
SDK_VERSION="${SDK_VERSION:-4.22.4.0.194092}" # The SDK version to sync
HERE_SDK_SWIFT_PACKAGES_REPO="git@your-git-server:here_sdk_swift_packages.git"
CLONE_DIR="here_sdk_swift_packages"

# --- iOS Specifics ---
IOS_SDK_HRN="hrn:here:artifact::olp-here:com.here.sdk:heresdk-navigate-ios"
ARTIFACT_ID="heresdk-navigate-ios-${SDK_VERSION}"
ZIP_NAME="${ARTIFACT_ID}.zip"
TAR_GZ_NAME="${ARTIFACT_ID}.tar.gz"

MAJOR_VERSION=$(echo $SDK_VERSION | cut -d. -f1-4)
DOWNLOAD_URL="https://artifact.api.platform.here.com/v1/references/${IOS_SDK_HRN}:${MAJOR_VERSION}/${ZIP_NAME}?apiKey=${HERE_API_KEY}"

echo "→ Cloning iOS SDK packages repo…"
rm -rf "${CLONE_DIR}"
git clone "${HERE_SDK_SWIFT_PACKAGES_REPO}" "${CLONE_DIR}"
cd "${CLONE_DIR}"

echo "→ Downloading HERE SDK for iOS v${SDK_VERSION}…"
curl -fSL "${DOWNLOAD_URL}" -o "../${ZIP_NAME}"

echo "→ Cleaning old framework (but keeping Package.swift)..."
rm -rf HERESDK.xcframework

echo "→ Unzipping and untarring new framework…"
unzip "../${ZIP_NAME}" -d .
tar -xzf "${TAR_GZ_NAME}"
rm "${TAR_GZ_NAME}"
rm "../${ZIP_NAME}"

echo "→ Committing & tagging v${SDK_VERSION}…"
git add .
git commit -m "Sync HERE SDK for iOS ${SDK_VERSION}"
git tag "v${SDK_VERSION}"
git push origin main --tags

echo "HERE SDK for iOS v${SDK_VERSION} mirrored successfully."

Step 3: Add the Package to Your App Using Xcode

In your Xcode project, navigate to File > Add Packages....

2. In the search bar at the top right, paste the URL of your private repository.

3. For Dependency Rule, choose your preferred strategy (e.g., "Exact Version").

4. Select the desired version from the list. The versions correspond to the tags created by the automation script.

5. Click Add Package.

Xcode will now automatically download and link the correct version of the SDK. To update, you can simply change the version rule in Xcode's "Package Dependencies" tab.