# Introduction Gigastore is a platform for reselling eSIM-based mobile data packages, which enables new and existing businesses to offer mobile data to their customers through a website or app. We offer a wide range of mobile data packages based on coverage (supported countries), validity (days), and volume (amount of Gigabytes) so you can address your customer needs. The mobile data packages can be installed by eSIM-capable devices and used immediately in the supported countries. No SIM card shipping is needed. To learn more about the Tunz eSIM, download the DENT App and try our eSIM service: . # Create an Account To start using Gigastore, first create an account. Open [Gigastore](https://dent.giga.store) in your web browser and click the "Register" button. Follow the instructions on the website. Once logged in, go to the **account** section by clicking on the account button the top right or following this [link](https://dent.giga.store/#/account/details). Please make sure that you have enter your personal information correctly, and enter your billing information. # Add Credits Once you have created your account and added your billing details, proceed by topping up your account with Gigastore credits. These credits are used to activate data packages in real time, so you don't have to pre-purchase specific packages to sell them in your shop. You only have to choose the packages you want to offer in your sales channels and ensure you have enough credits to keep selling data to your customers. To add credits, click on the [Wallet](https://dent.giga.store/#/credits) icon in the top right corner. Enter the amount of credits you want to add to your account. In the next step, select the payment method and check the stated VAT and total amount. {% hint style="warning" %} It is not possible to issue a refund of the VAT if you accidentally paid it. {% endhint %} Tap the "Pay now" button and perform the necessary steps for your payment method. {% hint style="info" %} Gigastore Credits are not refundable. {% endhint %} # Configure Inventory ### What is your Inventory? To offer mobile data packages, you will integrate our API or SDK into your front-end, e.g., mobile app or website. To control your offering, our APIs and SDKs will only allow activations of mobile data packages in your inventory, preventing unintended selling of mobile data packages and possible fraud attacks. ### Update your Inventory Once logged in, visit the [Store Inventory](https://dent.giga.store/#/your-store/inventory) at Gigastore. You can see a list of packages in your inventory. #### Add and Remove Packages To add a package, press the **"Add or Remove Packages"** button or visit the [Update Inventory](https://dent.giga.store/#/data-packages) section directly. Select the package(s) you want to offer by clicking on the "**+**" button next to the packages in the list. A checkmark icon will appear, showing that this package will be in your inventory after you apply the changes. To remove a package, press the checkmark button again.
Save your new inventory by clicking the "**Apply Changes**" button. You can check your current store inventory always in the [Store Inventory](< https://dent.giga.store/#/your-store/inventory>) section at Gigastore. #### Test Packages If you require test packages, we can provide you with free 10MB, 365-day validity packages for testing purposes. \ To get them, first, add the packages to your inventory as described above.\ Once added, please contact your Account Manager and we will activate testing packages for you. \ \ You can track the remaining packages in the "AMT" column on the left side of the [Store Inventory](https://dent.giga.store/#/your-store/inventory) section. #### Change Retail Price To define the price to your customers in your front-end, we recommend using the retail price. Tap the "**Edit**" button in your Store Inventory to change the retail price of the selected package. The Retail Price can be retrieved through our API endpoint. ### API Access To access the inventory of your Gigastore account from a front-end, you can use the `/gigastore/products/inventory` endpoint of our API. For more details, check our [API documentation.](https://dent.giga.store/#/api/specifications) # Set Up Auto Top-Up for Credits Auto Top-Up is a perfect way to ensure your account does not run out of balance and your customers receive their mobile data packages. ### How does it work? You define a threshold balance and top-up amount for your Gigastore account. Once your balance falls below your threshold, your account will be topped up automatically using your stored payment method. ### Add Payment Method To enable Auto Top-Up, first add your payment method. Gigastore supports different credit cards like Visa, Mastercard, and many more. Click on the [Wallet](https://dent.giga.store/#/credits) icon at the top right corner and click on the "Add Credit Card" button.
Next, fill out all the needed fields for your credit card. {% hint style="info" %} DENT is taking your personal data very seriously. We are **not storing** your credit card number. Instead, we are receiving an individual token from the credit card issuer that allows us to make payments later using this token. If you want to learn more you can read [here](https://stripe.com/en-de/resources/more/payment-tokenization-101) about payment tokenisation. {% endhint %} Once you add your payment method, it will be shown in the "Payment Method" section. ### Configure Auto Top-Ups Once you added your payment method, you can click on the "Enable Auto Top-Ups" button.
Continue by specifying the following fields: * **Balance Threshold** - The auto top-up will be triggered once your balance falls below this value. * **Automatic Top-Up amount** - The amount is added to your account every time the auto top-up is triggered. Complete the setup by clicking the **Activate Auto Top-up** button to save your settings. ### Update Threshold and Top-Up Amount As your business is growing it might be needed to update the Auto Top-Up settings at Gigastore. To update the settings, visit your [Store Inventory](https://dent.giga.store/#/your-store/inventory) and click the "Manage Auto Top-Up" button. Here you can change the threshold and top-up amount for your Gigastore account. ### Update payment method In case you need to update your payment method, follow these steps: 1. **Write down** your Auto Top-Up threshold and top-up amount 2. **Delete** your current payment method. This will deactivate the auto top-up feature. 3. **Add** your new payment method. See [#add-payment-method](#add-payment-method "mention") 4. **Re-enable Auto Top-up** with your written down values as described on [#configure-auto-top-ups](#configure-auto-top-ups "mention") # API Integration Gigastore offers an API to provide your customers with mobile data packages via a website or an app. The API also lets you handle specific cases on your server. To start integrating, visit the [Getting started](/api/getting-started) section. ### Credentials Integrate our API to activate and manage your customers' mobile data packages using the API credentials provided by Gigastore. Check our [API Documentation](/api/getting-started) for more details. ### Webhooks Use our webhooks to get updates from your users on Gigastore, such as a user's country change or eSIM status. The [Webhook documentation](/webhooks/first-steps) provides more details about our available webhooks. ### Integration Flow Before deep-diving into detailed specifications, look at the visual overview of the process for installing and activating your eSIM.

Image of Gigastore Sequence Diagram (API)

# SDK Integration In addition to our API, the Gigastore SDK allows your customers to install the eSIM with a tap of a button in your mobile app instead of scanning QR codes or entering activation codes in your device's settings. The SDK can also check the user device's eSIM capability. We recommend setting up the API integration first. ### Get Started You need a [Gigastore](https://dent.giga.store) account to use the [SDKs](https://dent.giga.store/#/sdk/ios-sdk) or [webhooks](/webhooks/first-steps) documented on this site. ### Credentials Integrate the iOS SDK or Android SDK into your mobile apps and use the SDK key and webhooks provided by [Gigastore.](https://dent.giga.store/#/sdk/ios-sdk) ### Integration Flow Before deep-diving into detailed specifications, look at the visual overview of the process for installing and activating eSIM.
{% file src="/files/cMYMR83UYsK7AMcRWiz2" %} Gigastore Sequence Diagram in PDF {% endfile %} # Getting started Gigastore provides an API for integrating eSIM into websites and mobile apps. The API is available in REST JSON format and comes with a Postman collection and Open API specification. Stay informed of our documentation to keep our API and services up-to-date. You can check the collections and specs here: [Postman Collection](/api/postman-collection) [Open API Specification](/api/open-api-specification) To start with an API integration, check the method to authorize your requests: [API Authentification](/api/api-authentification) Here, you will find the core elements of our APIs. [Offering Packages](/api/offering-packages) [Countries API](/api/countries-api) [Customers](/api/customers) [First Package](/api/first-package) [eSIM Profiles](/api/esim-profiles) [Top-up](/api/top-up) # Open API Specification You can find the latest Open API specification by following this link: [**Open API Specification**](https://dent.giga.store/#/api/specifications) # Postman Collection Gigastore provides a Postman collection for the Gigastore API. To use the collection, please follow these steps. 1. Make sure you use the latest version of [Postman](https://www.postman.com) 2. Use the "Import" function of Postman to add the collection using this URL: 3. Select the collection in Postman
4. Select the "Authenticate" request and right-click the URL address. Then click "Add new variable".
5. Set the variable to `https://api.giga.store` and choose the scope (recommended is `Collection`).
5. Switch to the "Authorization" tab of the request and set `resellerClientId` as a variable based on the **CLIENT ID** from your [Gigastore API page](https://dent.giga.store/#/api). 6. Set the `resellerClientSecret` as a variable based on the **CLIENT SECRET** from your [Gigastore API page](https://dent.giga.store/#/api). 7. Execute the Authorization request in Postman. The response contains the accessToken. If this is not the case, please double-check your variables.
{% hint style="info" %} To change variables, you need to remove the field content, paste the new value, select the value, and use the "Set as variable" popup. {% endhint %} 8. Copy the **complete** accessToken value. 9. Switch to the "Version" request and select the "Authorization" tab. Set the copied accessToken as the value of the `resellerAccessToken` variable.
10. Execute the request and check the response. It will show the server/API version.
🥳 Congrats! Your Gigastore API Postman collection is now ready. # API Authentification To authenticate with Gigastore backend, please use the credentials provided when logging in to your Gigastore account. {% hint style="info" %} API credentials and inventory are bound to the Gigastore login. \ Make sure to use the same login to create credentials and manage your inventory. {% endhint %} The credentials are **Client ID** and **Client Secret**, which can be found in the[ API section ](https://dent.giga.store/#/api)of the Gigastore portal.
Use the `/reseller/authenticate` endpoint with [Basic Authorization](https://en.wikipedia.org/wiki/Basic_access_authentication) using your **Client ID** as username and **Client Secret** as password to retrieve the accessToken. The snippet below can be generated by following the **"First Steps"** in the Gigastore API portal, or the base64 value needs to be calculated on your side. ``` curl --location --request POST 'https://api.giga.store/reseller/authenticate' --header 'Authorization: Basic base64(:)' Response: { "accessToken": "eyJhbGciOiJSUzI1NiIsInR5c..._very.long_string", "expiresIn": 86400, "refreshToken": null, "refreshExpiresIn": 0, "tokenType": "Bearer", "idToken": null } ``` Now, you can use the **accessToken** in your header as **Authorization Bearer** for other API calls needing authentification. ``` curl --location --request GET 'https://api.giga.store/gigastore/products/inventory' \ --header 'Authorization: Bearer eyJhbGciO...YOUR_ACCESS_TOKEN... Response: { // your inventory } ``` # Offering Packages The data packages that are offered to your users for sale are defined by the **inventory**. You can define the inventory following the [Configure Inventory](/start-with-gigastore/configure-inventory) section. The inventory API can be used to show available packages to the end-user. Gigastore offers an inventory of data packages (`items`) that differ in * Covered Countries * Size * Validity * Price Each item also has a unique **ID**, later referred as `inventoryItemId`. ``` GET /gigastore/products/inventory Response: { "items": [ { "id": "14ed2704-35ff-4feb-82a3-12345678abcd", "name": "eSIM Worldwide 50 MB", "sizeValue": 50, "sizeUnit": "MB", "validitySize": 365, "validityUnit": "days", "validityUnlimited": false, "countrySet": "WWW", "includedCountries": [ "string" ], "active": true, "profileDomainKey": "string", "packageType": "standard", "extendedDataPolicy": { "type": "standard", "resetType": "timeInterval", "interval": "24h", "fixedTime": "00:00", "throttleSpeed": "128 KB/s", "totalHighSpeedVolume": { "sizeValue": 0, "sizeUnit": "TB" } }, "prices": [ { "sortIndex": 0, "priceValue": 1.49, "currencyCode": "USD" } ], "amount": 1, "retailPriceEdited": true, "retailPrices": [ { "sortIndex": 0, "priceValue": 4.99, "currencyCode": "USD" } ], ... ``` ### Covered Countries Each package refers to a set of supported countries, the `countryset`. This set can contain one country (single country package) or many countries, like the Worldwide data package. You can find the supported countries set in the [Gigastore portal](https://dent.giga.store/#/data-packages) and via API in the [Countries API](/api/countries-api) section. ### Offering Mixed Coverage Each user on Gigastore supports only one `countrySet`. For example, if users register by activating a "Worldwide" package, they can only receive top-ups from the same coverage, "Worldwide." Any other package will result in a failed request. However, you can still assign multiple `countrySet` packs to a customer by registering a new user on Gigastore and saving that user's UID to link it with the customer in your system. Please note that each customer requires a separate eSIM for each `countrySet` type. For additional details, refer to the Customers section. ### Size The size of a data package defines the usable amount of data. The size is split into **sizeValue** and **sizeUnit**. * 50MB: sizeValue = 50 and sizeUnit = "MB" * 10GB: sizeValue = 10 and sizeUnit = "GB" These values can be used to show the user the size of the package. {% hint style="warning" %} Please remember that **1 GB equals 1024 MB.** {% endhint %} ### Validity Gigastore provides data packages with different days of validity to be sold and activated to end users. which The validity of a data package defines the period within the package can be used. The validity timer starts with the [activation](/api/first-package) of the package. The validity is split into **validitySize** and **validityUnit**. * 30 days: validitySize = 30 and validityUnit = "days" ### Price Each package has a purchase price and a retail price. The **purchase price** will be **deducted from your credit** balance when activating a package. The retail price is intended to be shown to your users. You can define the retail price for each package in the [Gigastore portal.](https://dent.giga.store/#/your-store/inventory?sortDir=ASC\&sortKey=price) The API will provide both prices: ``` "prices": [ { "sortIndex": 0, "priceValue": 1.49, "currencyCode": "USD" } ], "retailPrices": [ { "sortIndex": 0, "priceValue": 4.99, "currencyCode": "USD" } ], ``` The `retailsPrices` array refers to the **retail price** of the package. The `prices` array refers to the **purchase price** of the package. {% hint style="info" %} The API already supports multiple prices to be able to return different currencies later. We recommend filtering for *currencyCode=USD*. {% endhint %} # Countries API In the Gigastore API, each package relates to a country set. This country set defines the supported countries of this package and is represented by a string identifier. The number of countries in each country set can be just 1 - for single-country packages - or many such as for worldwide packages or regional packages. For each country set, you can check the containing countries using the `countries` endpoint. The country set of the worldwide package has the identifier `WWW`. To retrieve the included countries, use ``` GET /gigastore/esim/countries/WWW Response: [ { "code": "AU", "name": "AU", "imageUrl": "/esim/countries/au/flag" }, { "code": "AL", "name": "AL", "imageUrl": "/esim/countries/al/flag" }, ... ] ``` The country set of the Austria package has the identifier `AT`. ``` GET /gigastore/esim/countries/AT Response: [ { "code": "AT", "name": "AT", "imageUrl": "/esim/countries/at/flag" } ] ``` The endpoint returns a list of countries, including the **ISO2** code and the **endpoint URL** for the flag of this country. ### Flags Country flags are provided by the API in **PNG format**. Use the ISO2 code of the country to fetch the image: ``` GET /gigastore/esim/countries/AT/flag ``` ### Networks Each country has one or more providers of network towers (cell towers) supported by Gigastore. If an eSIM is installed and activated on a user's device, it will automatically try to connect to a supported tower close by. If the user owns a package covering this network, the access is granted and the data used is deducted from the package. Gigastore can provide clients with a list of supported networks per country on request. # Supported Devices API This endpoint provides the list of supported devices, including their names, vendors, and platforms.\ While we strive to keep this list up to date, it is not guaranteed to be fully comprehensive or reflect the latest changes. {% hint style="info" %} Please note that certain devices may be subject to country-specific restrictions. \ For example, devices sold in China may be listed but lack eSIM capabilities due to regulations. {% endhint %} To retrieve the list of eSIM-supported devices, use ``` GET /esim/device/esim-capable Response: [ { "name": "Pixel 2", "vendor": "Google", "platform": "Android" }, { "name": "Pixel 2 XL", "vendor": "Google", "platform": "Android" }, { "name": "Pixel 3 XL", "vendor": "Google", "platform": "Android" }, ... ] ``` # Customers To provide connectivity to your customers, you need to create at least one Gigastore Customer on the Gigastore API. A Gigastore Customer is an entity to which eSIM profiles and data packages are attached. Each Gigastore Customer belongs to a specific `countrySet` type used during registration. As a result, a request to activate a data package with a different country set will generate an error. To create a Gigastore Customer via API, you need to activate the [First Package](/api/first-package) and provide an email of the user. The API returns a `uid` that is used by API calls to top-up additional data packages to the Gigastore customer account. You can link several Gigastore Customers to a single customer if you wish to provide that individual with an eSIM featuring a different `countrySet` than what was originally registered. To do so, associate the Gigastore Customer UIDs to your customer directly in your platform.\ Remember that one Customer UID means one `countrySet`. This model enables you to offer eSIMs and data to your customers, while also monitoring their eSIM usage by country. ### Get all customers You can use the `/gigastore/activations/customers` endpoint to retrieve a list of all customers on your account. Each customer comes with details like `email` and `uid`, a `totalAvailableBalance`, a list of `activatedItems` and a list of `relatedEsims`. ``` GET /gigastore/activations/customers Response: [ "customer": { "email": null, "uid": "261ef0b4-b054-4a0f-9e06-ba9193b5c0a5", ... }, "totalAvailableBalance": { "sizeValue": 2, "sizeUnit": "GB" }, "activatedItems": [ { "uid": "0b35b82f-ae46-4717-96be-12345676789", "balance": { "activatedAt": "2024-03-23T10:53:47Z", "expiresAt": "2024-04-23T10:53:47Z", ... }, }, { "uid": "2342bc23-ae46-4717-96be-12345676789", "balance": { "activatedAt": "2024-04-23T10:53:47Z", "expiresAt": "2024-05-23T10:53:47Z", ... }, }, ], "relatedEsims": [ { "iccid": "891234567891234567890", "imsi": "260123456789012", "activationCode": "LPA:1$domain.tld$CODE123456789", "uid": "12345-abcdef-56789" // can be used as input for SDK ... } ] }, ... ] ``` ### Get specific customers To get a specific customer, you can use different methods: * Fetch the customer by UID by using the `gigastore/activations/customers/` endpoint * Search for a customer by using the `gigastore/activations/search-customers` endpoint ### Activated Items Gigastore supports the purchase/activation of multiple packages per customer. After the [First Package](/api/first-package), the [Top-up](/api/top-up) API can be used to add another data package to an existing customer. Please note that Top Ups work only within the same Country Set. The customer object contains a list of all activated packages (`activatedItems`). Each entry contains a balance object, including the date and time of purchase, the package size (e.g. 3GB), and the currently available balance (e.g. 1,3 GB). ### Total Balance This value sums up the customer's current available balance. Gigastore handles different events internally and provides a convenient method to get the current balance. This value is recommended for showing your users in the UI.
EventAct.Item SizeAct.Item IDBalance SizeTotal Balance
First Purchase1GB11GB1GB
Topup3GB23GB4GB
Usage of 0.5GB-10.5GB3.5GB
Item Expiry-10.5GB3GB
Usage of 0.7GB-22.3GB2.3GB
Topup5GB35GB7.3GB
### Related eSIMs When creating the customer through the [First Package](/api/first-package) request, an eSIM is created for this customer. That is the first related eSIM for a customer. In case a customer lost its device, an additional eSIM can be issued (e.g. through a support request on your side) and added to the customer. In this case, multiple related eSIMs can be returned by the API. The uid of the eSIM can be transported to your app and used with the SDK to install the eSIM directly on the device. Please see the [eSIM Profiles](/api/esim-profiles) section for details. # First Package When a user of your website or app is eligible to receive a mobile data package (e.g., the user made a purchase of an inventory item, and you received the money), you can issue the first data package. {% hint style="info" %} The activation will use your credit balance on Gigastore. You can check for the history of activations here: . {% endhint %} To activate, you need the following: * **inventoryItemId** - see [Offering Packages](/api/offering-packages) * **metatag**, e.g. an internal transaction id (will be stored and can be retrieved via API) * **customerEmail** - the email address of your customer (optional) * **userIp** - current IP of the user * **userCountry** - country of residence (use ISO2 code) * **expectedPrice** - the retail price of the package (optional) * **activationMode** - type of package activations (optional) see [Activation Modes](/api/activation-modes) {% hint style="info" %} To protect your payment flow, you can add the `expectedPrice` field. In this case, our API will check the price against the retail price of the inventory item. Only if the price matches will the API allow activation. {% endhint %} {% hint style="warning" %} In order to ensure compliance with regional regulations, make sure to include user's IP and Country of Residence during the registration. {% endhint %} ``` POST /gigastore/activations/register Request: { "inventoryItemId": "00e3e46e-faa5-465a-9321-1234567890", "metatag": "Comment for reseller...", "customerEmail": "customer_email@test.com", "userIp": "123.45.67.89", "userCountry": "GR", "expectedPrice":{ "sortIndex": 0, "priceValue": 9.99, "currencyCode": "USD" }, "activationMode": "NOW" } Response: { "status": "success", "activatedItem": { "balance": { "activatedAt": "2024-04-30T09:55:36.430Z", "expiresAt": "2024-04-30T09:55:36.430Z", "activationMode": "NOW", "name": "string", "size": { "sizeValue": 0, "sizeUnit": "TB" }, "availableBalance": { "sizeValue": 0, "sizeUnit": "TB" }, "validitySize": 365, "validityUnit": "years" }, "uid": "string", "metatag": "Paid in cash", "salesChannel": "Application Programming Interface", "salesChannelTypeCode": "API", "activationType": "DATA_PLAN", "purchasePrice": { "sortIndex": 1, "priceValue": 4.99, "currencyCode": "USD" }, "retailPrice": { "sortIndex": 1, "priceValue": 4.99, "currencyCode": "USD" } }, "customer": { "email": "customer_email@test.com", "uid": "123234345-234-cbd2-9321-1234567890", "profileUrl": "string" }, "esimProfile": { "iccid": "string", "uid": "string", "imsi": "string", "activationCode": "string", "appleUniversalLink": "string", "installationUrl": "string", "lastSeen": "2024-04-30T09:55:36.430Z", "activatedAt": "2024-04-30T09:55:36.430Z", "state": "RELEASED" } } ``` During the activation, different entries are created in the background and returned from the API: * a **customer** linked to your account * an **activated item**, linked to your customer * an **eSIM profile**, linked to your customer To use the package, the customer needs to install the eSIM profile. Please check the [eSIM Profiles](/api/esim-profiles) section for details. ### Multiple Packages and eSIMs Customers can have multiple activated items and multiple eSIM profiles. Please refer to the [Customers](/api/customers) section of the documentation. # Activation Modes The ActivationMode field allows to choose *when* a data package starts to be valid. #### **Three activation options are available:** * NOW: The data package activates immediately upon purchase (used by default). * FIRST\_USE: The data package activates only when the customer first connects to a network in the coverage area, perfect for travellers who want to start their package automatically when they reach their destination. * ON\_DEMAND: The data package activates when explicitly triggered via the API, provides full control over the activation timing. {% hint style="info" %} **ON\_DEMAND** activation is only available for **Worldwide** and **Regional** data packages. {% endhint %} Data packages using the options `FIRST_USE` or `ON_DEMAND` have a 90-day period to be fully activated. If the plan remains inactive after this period, the packages will automatically activate, and the validity will begin. This options are available in the following endpoints: * `/gigastore/activations/register` * `/gigastore/activations/top-up-with-profile` * `/gigastore/activations/top-up` The `activationMode` field is optional and defaults to NOW, ensuring existing integrations continue to work seamlessly. #### Best practices * Use `ON_DEMAND` for worldwide packs, as most people will already be located in a coverage area from the data package. * Use `FIRST_USE` activation for single-country and regional packs, as most people won't be located already in a coverage area. #### Important notes: * For FIRST\_USE or ON\_DEMAND modes, the `activatedAt` field in the Balance schema will be empty until activation, and the `expiresAt` field represents the latest date the package can be activated. \ If the plan remains inactive by this date, it will automatically activate. * Once activated, `activatedAt` is set to the current timestamp, and `expiresAt` is updated to reflect the package's duration from the activation time. * A `salesDate` field in the `activatedItem` schema indicates when the package was sold, distinct from `activatedAt`, which reflects the actual activation time. #### Endpoint for On-Demand Activation. To support the ON\_DEMAND activation mode, the following endpoint should be used:\ `POST /gigastore/activations/activated-items/{uid}/activate` This endpoint activates the balance of an item by its UID. \ UID in this case it's UID from `activatedItem` in response to `POST /gigastore/activations/register` endpoint.\ It also can be used for manual activation a FIRST\_USE package before using it. # eSIM Profiles An eSIM profile allows access to the mobile data network. The user can install an eSIM using different methods on an eSIM-capable smartphone: * Scan the Activation Code * Direct Installation via Universal link (recommended) ### eSIM API Object Each eSIM profile comes with * **uid** - identitier; used for SDK eSIM download * **ICCID** - main identifier for end-user support * **activationCode** - used to install the eSIM * **IMSI, lastSeen, activatedAt** - additional identifiers for support * **state** - current state (e.g. INSTALLED) ``` { "iccid": "89972123300991848961", "imsi": "260060145143896", "activationCode": "LPA:1$domain.tld$1234567890ABCDEF123456", "appleUniversalLink": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$$", "installationUrl": "https://dent.giga.store#/esim/profile?token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI4OTk3MjEyMzMwMDk5MTg0ODk2MSJ9.V34vHdqG6QD9iyCLjIfh2zxsv5MUUjEaOkSw3EY_RVJAxhQQfTeZBfEL_EYwAS9TMNi_Rn6L2Q2cuuI8Ve9zmQ", "lastSeen": null, "activatedAt": null, "state": "RELEASED", "uid": "7555cab8-72bc-4e85-b56a-6cdf60e2d6e4", "active": true } ``` ### Providing QR code for installation Once the [First Package](/api/first-package) is activated, the returned eSIM can be used to provide a QR code for installing the eSIM. You can use any QR code renderer to generate a QR code using the `activationCode` and provide it to your user via email or through other channels. The QR code must be scanned with an eSIM-capable device, like an iPhone 14.

Example QR code of
LPA:1$domain.tld$1234567890ABCDEF123456

iPhone identifies the code as "Mobile Plan"

### Direct installation via Universal Links On Android 10 and iOS 17.4 and above, users can install their eSIM directly on their devices by clicking a simple link.\ \ The Universal Link install method works by adding the unique SMDP+ address and Activation Code as parameters to the universal link URL, which can be tied to a button in your application.\ \ The universal link would look as follows: | OS | URL | Activation code | Universal Link Sample | | ------- | ---------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Apple | | LPA:1$SMDP+\_Address$Activation\_Code | | | Android | | LPA:1$SMDP+\_Address$Activation\_Code | | Important Notes for Implementation: 1. URL Casing: The base URL should always be lowercase to ensure compatibility and avoid processing errors. 2. Activation Code: The Activation Code may contain capital letters and should be entered strictly as provided. 3. External Link Configuration: If integrating this link within an app, configure it to open externally. This ensures that the device’s browser handles the activation, adhering to Apple’s setup protocols. SMDP+ address and Activation Code are provided with this request `POST /gigastore/activations/register` ### eSIM States An eSIM can have different states. You can use the eSIM state to guide the user during your user journey. | State | Meaning | Comment | | ----------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | | RELEASED | Not installed on a device | Profile ready to be downloaded and installed | | DISABLED | Installed, but user disabled the eSIM in the OS | Not available for all eSIM profiles / devices | | INSTALLED/ENABLED | Installed and enabled | Profile is already installed, and may already be turned on in user's device | | ERROR | Something went wrong during installation | Contact support to replace the profile. | To receive status updates, use the [eSIM Status](/webhooks/esim-status) webhook. The webhook is triggered within a few seconds after the user interaction. # Top-up Once the [First Package](/api/first-package) has been activated, you can add more balance to your Gigastore Customer via the `/gigastore/activations/top-up` endpoint.\ Please note that Top-ups can only be activated for existing Gigastore Customer and must match the `CountrySet` during the initial activation. {% hint style="info" %} The activation will use your credit balance on Gigastore and deduct the purchase value from your credit. You can check for the history of activations here: . {% endhint %} #### To activate a top-up, you need: * **inventoryItemId** - see [Offering Packages](/api/offering-packages) * **metatag**, e.g. an internal transaction id (will be stored and can be retrieved via API) * **customerUid** - the uid of your customer as returned during registration * **expectedPrice** - the retail price of the package (optional) * **activationMode -** type of package activations (optional) see [Activation Modes](/api/activation-modes) #### Top-up behavior * Top-ups are consumed in order of shortest remaining validity. * Inactive FIRST\_USE top-ups will not be used until all active package(s) are empty or expired. * Multiple inactive FIRST\_USE top-ups activate in order of the closest `expiresAt` date, usually matching the purchase order. * ON-DEMAND top-ups can be stacked and will remain inactive until manually triggered via API. * Top-ups activate and take priority for usage automatically based on coverage area, even if other plans are active. ``` POST /gigastore/activations/top-up Request: { "inventoryItemId": "00e3e46e-faa5-465a-9321-1234567890", "metatag": "Comment for reseller...", "customerUid": "123234345-234-cbd2-9321-1234567890", "expectedPrice":{ "sortIndex": 0, "priceValue": 4.99, "currencyCode": "USD" }, "activationMode": "NOW" } Response: { "status": "success", "activatedItem": { "balance": { "activatedAt": "2024-04-30T10:41:03.14304Z", "expiresAt": "2025-04-30T10:41:03Z", "activationMode": "NOW", "name": "eSIM Worldwide 50 MB", "size": { "sizeValue": 50, "sizeUnit": "MB" }, "availableBalance": { "sizeValue": 0.05, "sizeUnit": "GB" }, "validitySize": 365, "validityUnit": "days" }, "uid": "4f1eec1b-61dc-47df-91a6-....", "metatag": "Comment for reseller...", ... }, "customer": { "email": null, "uid": "123234345-234-cbd2-9321-1234567890", "profileUrl": "" }, "esimProfile": null } ``` The request will return a newly created **activatedItem**. The customer's total balance will be updated immediately. See [Customers](/api/customers) for more details. {% hint style="info" %} The top-up is instantly usable by your user; no additional eSIM needs to be installed. {% endhint %} # Package Refund Gigastore provides Credit Refunds for data packages if a customer cannot use the purchased package due to a technical issue. Refunds via API will be processed if all the following conditions are met: 1. **Package Purchase**: The package must have been purchased using Credits via Gigastore. 2. **Package Status**: The data package must still be valid (not expired) and unused (full data). 3. **Refund Limit**: You have not exceeded the maximum number of refunds allowed this month. When these conditions are satisfied, the Credits for the package will be refunded to your Gigastore Account. Otherwise, the system will return an error. To conduct a refund via API, use the following route: ``` /activations/activated-items/{uid}/refund: post: summary: Refund an activated Item by its UID description: Refund an activated Item with the UID passed as a parameter in the path operationId: refundActivatedItem parameters: - in: path name: uid schema: type: string description: UID of the activated item, generated by the system required: true responses: 200: description: ok ``` Replace `{uid}` with the unique identifier of the purchased package. \ The UID of the purchased package can be retrieved via [activated-items](https://dent.giga.store/#/api/specifications). Refunds can also be processed through Customer Support or the Gigastore platform.\ For more detailed information, please proceed [here](/customer-support/package-refund). # Error Handling This section contains errors that can occur during implementation and how you can avoid them.
CodeTextTopicWorkaround
403{active = false}Authentification IssueCheck your authentification headers
# First Steps ### About Webhooks A webhook is a network communication initiated by Gigastore to your backend. It is used to keep your backend up-to-date when information changes at Gigastore. Use our webhooks to get updates from your users on Gigastore, such as a user's [country change](/webhooks/country-change), [eSIM status](/webhooks/esim-status), or when a user's balance[ runs low](/webhooks/low-balance-alert). Instead of polling our API for information, updates are pushed to your server, and you can inform your users about these updates through push notifications or emails. ### Technical Integration Gigastore needs to know the endpoints to send updates to your backend. A separate endpoint is needed for each update (country change, balance alerts). You can configure the endpoint URLs in the [Gigastore portal](https://dent.giga.store/#/api).

Webhook configuration

After adding the URLs in the portal, you can trigger the eSIM status webhook by installing or de-installing an eSIM from your Gigastore account from a device. After a few seconds, the webhook will be triggered, and information about the status update will be sent to your server. {% hint style="info" %} To test webhooks, we recommend using a site such as . {% endhint %} # eSIM Status Gigastore is sending the webhook as POST request providing the users after they have installed an eSIM profile on a device. The request sends the users' ID and the eSIM profile status "**Installed**". {% hint style="info" %} Please add your server URL on [Gigastore](https://dent.giga.store/#/api). \ Only **HTTPS** server URLs are allowed. {% endhint %} ### Request Parameters | Attribute | Type | Example | Info | | ------------ | ------ | -------------------- | -------------- | | iccid | string | 89361123300836129514 | - | | imsi | string | 260216611193634 | - | | profileState | string | INSTALLED | - | | eid | string | 74088234238931452 | Optional field | #### Sample request ``` { "iccid": "89361123300836129514", "imsi": "260216611193634", "profileState": "INSTALLED", "eid": "74088234238931452", } ``` # Balance Activation Gigastore sends notifications via webhook as a POST request whenever a data balance is activated. The notification helps you stay aware when users start using mobile data, which is especially important when using [first\_use](/api/activation-modes#three-activation-options-are-available) or [on\_demand](/api/activation-modes#three-activation-options-are-available) activation methods. {% hint style="info" %} Please add your server URL on [Gigastore](https://dent.giga.store/#/api). \ Only **HTTPS** server URLs are allowed. {% endhint %} ### Request Parameters | Attribute | Type | Example | Info | | ------------- | ------ | ------------------------------------ | ----------------------------------- | | uid | string | 058c8716-47dd-4fc4-be89-00978a86b7c0 | ID of the Gigastore Customer | | activatedItem | string | a15bb850-c166-4941-aef6-24fdbe27722d | Item ID of the balance | | activatedAt | string | 2025-08-25T09:52:10Z | Date when the balance was activated | | expiresAt | string | 2025-09-02T10:15:30Z | Date when the balance will expire | #### Sample request ``` { "uid": "058c8716-47dd-4fc4-be89-00978a86b7c0", "activatedItem": "a15bb850-c166-4941-aef6-24fdbe27722d", "activatedAt": "2025-08-25T09:52:10Z", "expiresAt": "2025-09-02T10:15:30Z" } ``` # Low Balance Alert Gigastore is sending the webhook as POST request providing the customers that are running low on eSIM data. The **low data threshold** is set to **100 MB**, so all customers who pass the threshold will appear on the request. {% hint style="info" %} Please add your server URL on [Gigastore](https://dent.giga.store/#/api). \ Only **HTTPS** server URLs are allowed. {% endhint %} ### Request Parameters | Attribute | Type | Info | | ------------------- | -------- | ------------------------------------ | | uid | string | 058c8716-47dd-4fc4-be89-00978a86b7c0 | | iccid | string | 89361123300836129514 | | imsi | string | 260216611193634 | | timestamp | dateTime | 2022-08-21T10:15:30Z | | balanceAmountInByte | long | 93618231 | #### Sample request ``` { "uid": "058c8716-47dd-4fc4-be89-00978a86b7c0", "iccid": "89361123300836129514", "imsi": "260216611193634", "timestamp": "2022-08-21T10:15:30Z", "balanceAmountInByte": 93618231 } ``` # Custom Data Consumption Gigastore is sending this webhook as a POST request whenever a customer's data consumption reaches one of your configured consumption thresholds. Each threshold is a **percentage of the original package allowance consumed** (for example 60%, 80%, or 100% = package fully used up). You can configure up to three thresholds, and each one is triggered once per package. The *configuredThresholdPercentage* field tells you which threshold was crossed. {% hint style="info" %} Please add your server URL on [Gigastore](https://dent.giga.store/#/api). \ Only **HTTPS** server URLs are allowed. {% endhint %} ### Request Parameters
AttributeTypeExample
AttributeTypeInfo
uidstring058c8716-47dd-4fc4-be89-00978a86b7c0
iccidstring89361123300836129514
imsistring260216611193634
timestampdateTime2022-08-21T10:15:30Z
configuredThresholdPercentagenumber80 (percentage consumed that was crossed; decimals like 12.5 are possible)
balanceAmountInBytelong93618231
originalBalanceAmountInBytelong1073741824
activatedItemIdstringa1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
#### Sample request ``` { "uid": "058c8716-47dd-4fc4-be89-00978a86b7c0", "iccid": "89361123300836129514", "imsi": "260216611193634", "timestamp": "2022-08-21T10:15:30Z", "balanceAmountInByte": 214748365, "configuredThresholdPercentage": 80, "activatedItemId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "originalBalanceAmountInByte": 1073741824 } ``` # Country Change Gigastore sends a response every time that the eSIM connects to a new country. The response comes with the IMSI, ICCID and the previous and new country where the eSIM is connecting to. You can determine if the eSIM is connecting for the first time when the response sends "**null**" on the previousCountry field. {% hint style="info" %} Please add your server URL on [Gigastore](https://dent.giga.store/#/api). \ Only **HTTPS** server URLs are allowed. {% endhint %} ### Request Parameters | Attribute | Type | Example | Info | | --------------- | ------ | -------------------- | ------------------------------------------------------------------------ | | imsi | string | 123456789012345 | | | iccid | string | 12345678901234567890 | | | previousCountry | string | DE | The request will send "null", when the eSIM connects for the first time. | | newCountry | string | US | | #### Sample Request ``` { "imsi": "123456789012345", "iccid": "12345678901234567890", "previousCountry": null, "newCountry": "DE" } ``` # First Steps Gigastore iOS SDK for installing eSIMs in third party apps ## Prerequisites You need a [Gigastore](https://dent.giga.store) account to use the SDK. Make sure that your Gigastore [inventory](https://dent.giga.store/#/your-store/inventory) is filled up. Using this SDK you can pick (activate) an eSIM from your inventory and install eSIM profiles through your app on a user's device. For the initialization, you need an SDK Key found on [Gigastore](https://dent.giga.store/#/sdk/ios-sdk). ## Technical Requirements {% hint style="warning" %} The eSIM installation works only iOS 12.1+ {% endhint %} * iOS 11.0+ * Xcode 12+ * Swift 5.x+ ## Supported devices * iPhone 15, iPhone 15 Plus, iPhone 15 Pro, iPhone 15 Pro Max * iPhone 14, iPhone 14 Plus, iPhone 14 Pro, iPhone 14 Pro Max * iPhone 13, iPhone 13 Pro, iPhone 13 Pro Max, iPhone 13 Mini * iPhone 12, iPhone 12 Pro, iPhone 12 Pro Max, iPhone 12 Mini * iPhone SE (2020, 2022) * iPhone 11, iPhone 11 Pro, iPhone 11 Pro Max * iPhone XR, iPhone XS, iPhone XS Max # Download SDK You can download the SDK using one of the supported package managers. ## PackageManager Use a package manager of your choice to integrate the SDK into your Xcode project: * [CocoaPods](/ios/installation#cocoapods) * [Carthage](/ios/installation#carthage) * [Swift Package Manager](/ios/installation#swift-package-manager) * [Manually](/ios/installation#manually) {% hint style="info" %} Please don't forget to [Add Build Phase](/ios/installation#attention-1) after setting up the package manager. {% endhint %} ### [CocoaPods](https://guides.cocoapods.org/using/using-cocoapods.html) **Note**: This feature is only available with CocoaPods 1.10.0 or later. In your `Podfile`: ```swift use_frameworks! platform :ios, '11.0' target 'TARGET_NAME' do pod 'DENTGigastoreSDK', :git => 'https://github.com/dent-telecom/gigastore-ios-sdk.git', :tag => '1.0.0' end ``` Replace `TARGET_NAME`. Then, in the `Podfile` directory, type: ``` $ pod install ``` ### [Carthage](https://github.com/Carthage/Carthage) In your `Cartfile`: ```swift binary "https://camelapi.io/ios-sdk/release/DENTGigastoreSDK.json" ~> 1.0.0 ``` See the [Carthage doc](https://github.com/googlemaps/google-maps-ios-utils/blob/main/docs/Carthage.md) for further installation instructions. ### [Swift Package Manager](https://github.com/apple/swift-package-manager) **Note**: This feature is only available with Swift 5.3 (Xcode 12) or later. Add the following to your `dependencies` value of your `Package.swift` file. ```swift dependencies: [ .package( url: "https://github.com/dent-telecom/gigastore-ios-sdk.git", from: "1.0.0") ) ] ``` ### Manually **Embed Framework** * Open up Terminal, `cd` into your top-level project directory, and run the following command "if" your project is not initialized as a git repository: ``` $ git init ``` * Add DENTGigastoreSDK as a git [submodule](https://git-scm.com/docs/git-submodule) by running the following command: ``` $ git submodule add https://github.com/dent-telecom/gigastore-ios-sdk.git ``` * Or [download](https://github.com/dentwireless/gigastore-ios-sdk) the `DENTGigastoreSDK.xcframework` manually * Open the new `DENTGigastoreSDK` folder, and drag the `DENTGigastoreSDK.xcframework` file into the Project Navigator of your application's Xcode project. > It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter. * Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar. * In the tab bar at the top of that window, open the "General" panel. * Go to the "Embedded Binaries" section. * Set the checkmark for "Code Sign On Copy" on the `DENTGigastoreSDK.xcframework` * And that's it! > The `DENTGigastoreSDK.xcframework` is automatically added as a target dependency, linked framework and embedded framework in a copy files build phase. This is all you need to create a build for the simulator or a device. ​ # Enable Direct Installation A direct installation allows users to install an eSIM on their iOS device without a QR code. Direct installations provide the smoothest experience for installing an eSIM. To enable the direct installation on an iOS device, please make sure to perform these steps on your Xcode project: 1. Request the **Direct Installation** at Gigastore and follow the process 2. Once approved, proceed with the technical integration {% hint style="info" %} The **Direct Installation** feature is not available for these kind of apps: \ \- eSIM Marketplace apps\ \- Apps from Mobile (Virtual) Network Operators\ \- VPN apps {% endhint %} ## Request Direct Installation To download an eSIM in your app through Apple’s eSIM API, we need to register your app. To start this process, please [submit a request here](https://survey.typeform.com/to/c93cGRie). Once the request has been received, we will schedule your request and guide you through the process. {% hint style="info" %} Be aware that the entire process can take several weeks. Once approved, you can start with the technical integration. {% endhint %} ## Technical Integration ### Info.plist and Entitlements Your Info.plist and your \.entitlements must be extended. Please make sure that you have an **entitlements file** in your project/target. An additional build phase will take care of the update of your Info.plist and the entitlements file: ### Add Build Phase ``` "'PATH_TO_THE_SDK'/DENTGigastoreSDK.xcframework/Scripts/Run.sh" \ "${PROJECT_DIR}/${INFOPLIST_FILE}" \ "${PROJECT_DIR}/PATH_TO_THE_ENTITLEMENTS/.entitlements" ``` * In the tab bar at the top of the window, open the "Build Phases" panel. * Above the "+" icon, add a "New Run Script Phase". * Add this line with the path to the SDK script, the path to your Info.plist, and the path to your \.entitlements file. ### Provisioning Profile For using Direct Installation you need to create a provisioning profile with "eSIM entitlements" enabled. To do so, please follow these steps: 1. Log in to your [Appstore Developer](https://developer.apple.com) portal 2. Start the assistant to [Register a new provisioning profile](https://developer.apple.com/account/resources/profiles/add) for the type of build 3. Select the needed App ID, certificate, and devices for your app 4. Select "eSIM Development" in the "Additional Entitlements" section (See screenshot below)
{% hint style="info" %} If this screen is not visible to you, please make sure you followed the process for enabling the direct installation with Gigastore already. If the process was done and you still don't see the profile, please double-check the Team ID on the top right with the Team ID mentioned in your request. {% endhint %} ### Manual Signing Apple only supports manual signing when using eSIM entitlements. In case you're using Automatic Signing you need to update your project. If you are unfamiliar with Manual Signing, please check the [Apple Developer documentation](https://developer.apple.com/help/account/get-started/about-your-developer-account). Make sure you manually create the [provisioning profile](#provisioning-profile) that supports your [**test devices**](https://developer.apple.com/help/account/register-devices/register-a-single-device) and your correct [**App ID**](https://developer.apple.com/help/account/manage-identifiers/register-an-app-id). # iOS Universal Link With iOS 17.4 and above, Apple has introduced the ability for users to install their eSIM directly onto their devices by clicking a simple link.\ \ The[ Universal Link](https://developer.apple.com/ios/universal-links/) installation method works by appending the unique SMDP+ address and Activation Code as parameters to the universal link URL, which can be tied to a button in your application.\ \ The universal link would look as follows: | URL | Activation code | Universal Link Sample | | -------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | | LPA:1$SMDP+\_Address$Activation\_Code | | | | LPA:1$rsp.truphone.com$JQ-209U6H-6I82J5 | | Important Notes for Implementation: 1. URL Casing: The base URL should always be in lowercase to ensure compatibility and avoid errors in processing. 2. Activation Code: The Activation Code may contain capital letters and should be entered strictly as provided. 3. External Link Configuration: If integrating this link within an app, configure it to open externally. This ensures that the device’s browser handles the activation, adhering to Apple’s setup protocols. SMDP+ address and Activation Code are provided with this request POST /gigastore/activations/register
# Integrate SDK ## Import Import the `DENTGigastoreSDK` into your file. ```swift import DENTGigastoreSDK ``` ## Load The `load` method initializes the Gigastore SDK. Please make sure to include your "SDK Key" here. You can find your SDK Key in the [Gigastore](https://dent.giga.store) under "SDK -> iOS -> Sales Channel". ``` let sdkKey = "SDK KEY" ​Gigastore.load(withSDKKey: sdkKey) ``` ## Set UserToken​ Please use an identifier from your system. You can e.g. use a self-signed JSON Web Token (JWT) as the `userToken`. That way you are able to verify the requesting device on your server when receiving the activation request webhook from Gigastore. ``` let userToken = "USER_TOKEN_1234567" ​Gigastore.setUserToken(userToken: userToken) ``` {% hint style="info" %} This parameter will be provided in the [ActivationRequest Webhook](/sdk-webhooks/activationrequest) to enable your server to check if the user is eligible to activate an eSIM. This parameter will **not be stored** on our servers. {% endhint %} # Prepare eSIM Installation ### Check for eSIM capable device First, you need to check if the device is eSIM capable. {% hint style="warning" %} This query may take some time (up to multiple seconds on some devices) to complete. Make sure you wait for the completion before triggering an eSIM installation. {% endhint %} ```swift Gigastore.isEsimCapable(completion: { (isCapable) in print("\(isCapable)")} ) ``` {% hint style="info" %} If a "false" is returned from the query despite the following criteria being met: * Your [device](/technical-integration/master#supported-devices) is eSIM capable * You have added the [run script](/ios/installation#attention-1) for your [Info.plist](/ios/installation#info-plist-and-entitlements) and your [entitlements](/ios/installation#info-plist-and-entitlements) file. Then there is likely another problem. If this problem persists, **please contact ** {% endhint %} The `isEsimCapable` method can be used to check whether the user's device is eSIM capable or not. ## Activate Inventory Item using API {% hint style="warning" %} Implementation changed with SDK version 1.1. {% endhint %} To install an eSIM, an inventory item must first be activated using the Gigastore API on your server. For more information, refer to the [First Package](/api/first-package)API documentation. Use the **esimProfile.uid** parameter of the API response and transfer it securely to your app. ## Retrieve the profile Use the `getProfile` method with the created profile uid to fetch all needed profile data. \ The method will return a profile you can install in the next step using [Install Profile](/ios/install-profile). ```swift let profileUID = "123456-abcde-abcde-789" // from API Gigastore.getProfile(profileUID: self.profileUidValue, completion: { (profile, error) -> Void in print("PreparedProfile: \(profile), error: \(error)") }) ``` # Install eSIM ### Direct Installation The `installProfile` method can be used to install an eSIM profile on a user's device. The device operating system will show up an installation wizard for the user. ``` let profile = Gigastore.installProfile(profile: profile, completion: { (profile, error) in print("profile: \(profile)") print("error: \(error)") }) ``` This function returns either the installed profile or an error object containing the error. ### QR Code Installation Due to restrictions, **Direct Installation** might not be available for some apps. In this case, you can use the iOS QR code feature. First, generate a QR code based on the `activationCode` of the `profile` object. Several libraries generate QR codes on iOS. Ensure you generate a QR code with a valid activation code starting with *LPA$*. Then, provide the QR code to the user via email or as an image in your app that can be saved to photos. {% hint style="info" %} Please add a proper UX to explain to your users how to install the eSIM profile. {% endhint %} Check our [eSIM Profiles](/api/esim-profiles) section of our API if you want to initiate this process from your app middleware. # Profiles ### Retrieve profiles The `getAllProfiles` function can be used to return all eSIM profiles created for the device. An error is returned if the request can't be fulfilled. ```swift Gigastore.getAllProfiles(completion: { (profiles, error) in print("Profiles: \(profiles ?? [])") print("Error: \(error)") }) ``` ### Profile Object The profile contains several identifiers, states and methods: * **id -** internal id of the profile * **state** - returns the current profile state. See [eSIM Profiles](/api/esim-profiles#esim-states)for details of the relevant states. * **imsi -** IMSI (International Mobile Subscriber Identity) of the eSIM profile * **iccid** - ICCID (Integrated Circuit Card Identification number) of the eSIM profile. Used for support cases and main identifier. The ICCID of an installed profile is also accessible for the user in the OS settings. * **isValidEsimProfile()** - returns true, if the object instance contains all the necessary information * **isInstalled() -** returns true, if the profile is installed (and active) on the device. {% hint style="info" %} To check if a profile is installable, use `profile.state == .released`. {% endhint %} # First Steps Gigastore Android SDK for installing eSIMs in third party apps ## Prerequisites The Gigastore Android SDK extends our Gigastore API with the capability to install an eSIM profile directly. * You need a [Gigastore](https://dent.giga.store) account to use the SDK. * You need a server integration with the [Gigastore API](/api/getting-started). * Make sure that your Gigastore [inventory](https://dent.giga.store/#/your-store/inventory) is filled up. Using this SDK, you can install an eSIM of one of your customers through your app on a user's device. * For the initialization, you need an SDK Key found on [Gigastore](https://dent.giga.store/#/sdk/ios-sdk). {% hint style="info" %} We created an example app to demonstrate how the SDK should be implemented and allow developers to test synchronization with Gigastore inventory. The app can be found [here](https://github.com/dent-telecom/gigastore-android-sdk-example-app). {% endhint %} ## Technical Requirements * Android Studio latest version * uses Android 9 or higher * target at least API level 28 ### Proguard, R8 Recommended environment: * AndroidStudio 4.1+ * Gradle 6.5+ The Gigastore SDK will configure your app's Proguard, R8 rules using proguard-rules.txt. ```bash # Proguard configuration for Gigastore SDK 1.x.x -keep class com.dentwireless.GigastoreSdkKt { *; } -keep class com.dentwireless.gigastore_sdk.** { *; } ``` ## Supported devices Check your device for an eSIM feature to verify its capabilities. These are some of the Android-supported devices: * Google Pixel 8 Series * Google Pixel 7 Series * Google Pixel 6 Series * Google Pixel 5 Series * Google Pixel 4 Series * Google Pixel 3a, Pixel 3a XL * Samsung Galaxy S24 Series * Samsung Galaxy S23 Series * Samsung Galaxy S22 Series * Samsung Galaxy S21 Series * Samsung Galaxy S20 Series * Samsung Galaxy Fold * Samsung Galaxy Z Flip * Huawei P40 * Huawei P40 Pro * Motorola Razr (2019) * Nuu Mobile X5 * Rakuten Mini # Download SDK You can download the SDK using one of the supported package managers. ## PackageManager Available via [Jitpack](https://jitpack.io/#dent-jitpack/gigastore-android-sdk). We recommend using gradle for adding the dependency ### Gradle Add it to your root build.gradle at the end of repositories: ```ruby allprojects { repositories { ... maven { url 'https://jitpack.io' } } } ``` Add the dependency to your app/library build.gradle ```groovy implementation ("com.github.dent-jitpack:gigastore-android-sdk:1.1.0") { transitive=true } ``` # Enable Direct Installation A direct installation allows users to install an eSIM on their Android device without a QR code. It provides the smoothest experience for installing an eSIM. 1. Request the **Direct Installation** at Gigastore and follow the process 2. Once approved, proceed with the technical integration ## Prepare SHA-1 To use the Gigastore Android SDK in your app, you need to provide the certificate fingerprint of your app to DENT. If your app is **self-signed**, identify the SHA-1 using `keytool` following [Google documentation](https://developers.google.com/android/guides/client-auth). If you are using **Play App Signing**, provide the bundle SHA-1 from the [Google Play Console](https://play.google.com/console/developers/app/keymanagement). {% hint style="info" %} **App Bundles** might have a different signature in Google Play than during testing the APK locally. In this case, change your App Bundle signature to your self-signed key (see this [link](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en#zippy=%2Cdescriptions-of-keys-artifacts-and-tools%2Capp-signing-key-requirements)) or provide both SHA-1 fingerprints to Gigastore. {% endhint %} ## Request Direct Installation Once you identified the correct fingerprint, send us your SHA-1 via [this form.](https://survey.typeform.com/to/MT8yktD2) Registering your app might take some days. We will send you an email once your app has been registered. Schedule enough time to get the signature processed. # Android Universal Link With Android 10 and above, Android has introduced the ability for users to install their eSIM directly onto their devices by clicking a simple link.\ \ The Universal Link install method works by adding the unique SMDP+ address and Activation Code as parameters to the universal link, which can be tied to a button in your application.\ \ The universal link would look as follows: | URL | Activation code | Universal Link Sample | | ---------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | | LPA:1$SMDP+\_Address$Activation\_Code | | | | LPA:1$rsp.truphone.com$JQ-209U6H-6I82J5 | | Important Notes for Implementation: 1. URL Casing: The base URL should always be in lowercase to ensure compatibility and avoid errors in processing. 2. Activation Code: The Activation Code may contain capital letters and should be entered strictly as provided. 3. External Link Configuration: If integrating this link within an app, configure it to open externally. This ensures that the device’s browser handles the activation, adhering to Apple’s setup protocols. SMDP+ address and Activation Code are provided with this request POST /gigastore/activations/register
# Integrate SDK ## Import Import the `DENTGigastoreSDK` into your file. ```kotlin import com.dentwireless.Gigastore ``` ## Load The `load` method initializes the Gigastore SDK. Please make sure to include your "SDK Key" here. You can find your SDK Key in the [Gigastore](https://dent.giga.store) under "SDK -> Android -> Sales Channel". Call this in the `onCreate()` from the activity where you plan to use the SDK or an `Application` subclass. Make sure to add a `Context`. ```kotlin val sdkKey = "SDK KEY" ​Gigastore.load(context, sdkKey) ``` # Prepare eSIM Installation ### Check for eSIM capable device First, you need to check if the device is eSIM capable. {% hint style="warning" %} This query may take some time to complete. {% endhint %} ```kotlin Gigastore.isEsimCapable { isCapable -> Log.i("GigastoreSDK", "isCapable: $isCapable") } ``` {% hint style="info" %} If a "false" is returned from the query despite the following criteria being met: * Your [device](/technical-integration/master#supported-devices) is eSIM capable Then there is likely another problem. If this problem persists, **don't hesitate to contact ** {% endhint %} The `isEsimCapable` method can be used to check whether the user's device is eSIM capable or not. ## Activate Inventory Item using API {% hint style="warning" %} Implementation changed with SDK version 1.1. {% endhint %} To install an eSIM, an inventory item must first be activated using the Gigastore API on your server. For more information, refer to the [First Package](/api/first-package)API documentation. Use the **esimProfile.uid** parameter of the API response and transfer it securely to your app. ## Retrieve the profile Use the `getProfile` method with the created profile uid to fetch all needed profile data. \ The method will return a profile you can install in the next step using [Install Profile](/ios/install-profile). ```kotlin val profileUID = "123456-abcde-abcde-789" // from API Gigastore.getProfile(CONTEXT_PLACEHOLDER, profileUID) { profile, error -> Log.i("GigastoreSDK", "PreparedProfile: $profile) Log.i("GigastoreSDK", "error: $error") }) ``` Make sure to replace `CONTEXT_PLACEHOLDER` with your current Activity or Application context. # Install eSIM Use the `installProfile` to install an eSIM profile on a user's device. The device operating system will show up an installation wizard for the user. Use the output of the `getProfile` method (see [Prepare eSIM Installation](/android-sdk/activate-inventory-item)) to install a dedicated profile on the device. ```kotlin val profile = Gigastore.installProfile(CONTEXT_PLACEHOLDER, profile) { profile, error -> Log.i("GigastoreSDK", "Profile: $profile") Log.i("GigastoreSDK", "Error: $error") }) ``` Make sure to replace `CONTEXT_PLACEHOLDER` with your current Activity or Application context. This function returns either the installed profile or an error object containing the error. ### Release Mode To install an eSIM profile directly on an Android app, the app needs to be signed properly, and the SHA1 of the Keystore needs to be registered at Gigastore. As debug builds often don't sign the app with the production keystore, please make sure to test the installation with the keystore by running a **Release Variant Build**. # Profiles ### Retrieve profiles The `getAllProfiles` function can be used to return all eSIM profiles created for the device. An error is returned if the request can't be fulfilled. 
Gigastore.getAllProfiles { profiles, error ->
    Log.i("GigastoreSDK", "Profiles: $profiles")
    Log.i("GigastoreSDK", "Error: $error")
})
### Profile Object The profile contains several identifiers and states. * **id -** internal id of the profile * **state** - returns the current profile state. See [eSIM Profiles](/api/esim-profiles#esim-states)for details of the relevant states. * **imsi -** IMSI (International Mobile Subscriber Identity) of the eSIM profile * **iccid** - ICCID (Integrated Circuit Card Identification number) of the eSIM profile. Used for support cases and main identifier. The ICCID of an installed profile is also accessible for the user in the OS settings. * **isValidEsimProfile()** - returns true, if the object instance contains all the necessary information * **isInstalled() -** returns true, if the profile is installed (and active) on the device. {% hint style="info" %} To check if a profile is **installable**, use\ `profile.state == GigastoreESIMProfile.State.Released` . {% endhint %} # Testing ### Reset device During implementation, installing different profiles on one device can be necessary. As the default behavior of the SDK is to offer the same profile on a device for reinstallation, the test device needs to be reset to issue a new profile. With the first call of the "load" function of the Gigastore SDK, a token is stored in the **SharedPreferences** of your app to identify this device. To reset this device (and receive a new profile) you need to reset the **SharedPreferences** of your app. Please refer to the Android developer documentation on how to reset the **SharedPreferences.** ### Installing returns Error 2600 If you experience error 2600 on your Android device during [Install eSIM](/android-sdk/install-profile), it means the operating system does not allow direct installation. In this case, please check: * the device is not SIM-locked * your app is signed * the SHA1 of the certificate used for signing is the same that was provided to Gigastore ### Installing returns "The device could not be verified" If you experience this error on your Android device during [Install eSIM](/android-sdk/install-profile), it means the Gigastore server does not allow direct installation for this device. In this case, please check based on the error message: * **"Remote Verification failed":** Your activation webhook failed. Please make sure your server returns status code 200 and "SUCCESS" * **Device ID mismatch:** Your device was registered for another SDK key. Please make sure to [reset your device](#reset-device) after changing the SDK key. # Activation Request To approve an eSIM activation via SDK, you need to implement this callback on your server. If the client is allowed to install an eSIM, a successful response is expected from our backend. Gigastore is sending the webhook as a POST request. {% hint style="info" %} Please provide your server URL to your Gigastore contact. \ Only **HTTPS** server URLs are allowed. {% endhint %} ### Request Parameters | Attribute | Type | Example | Info | | --------------- | ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | inventoryItemId | string | 1\_GB |

The inventoryItemId from Gigastore
that you provided in activateItem

| | userToken | string | USER\_TOKEN\_1234567 |

The userToken you provided
in setUserToken

| | metaTag | string | myTag |

The metaTag you provided in

activateItem

| | activationId | string | 1e0da3933156 | A unique id provided for reference. | #### Sample Request ``` { "inventoryItemId": "1_GB", "userToken": "USER_TOKEN_1234567", "metaTag": myTag, "activationId": "1e0da3933156" } ``` ### Response Parameters | Attribute | Type | Limitation | | ----------------- | ------ | ------------------- | | **returnCode** | string | "SUCCESS" or "FAIL" | | **returnMessage** | string | - | #### Sample Response ``` {"returnCode":"SUCCESS","returnMessage":null} ``` {% hint style="info" %} Your server should always return 200. {% endhint %} # Customer Registration After the first activation of a user using the SDK, Gigastore sends the webhook as a POST request, providing the customers with the UID needed for later top-ups. On your server, you must implement a callback sending the user's email. {% hint style="info" %} Please add your server URL on [Gigastore](https://dent.giga.store/#/api). \ Only **HTTPS** server URLs are allowed. {% endhint %} ### Request Parameters | Attribute | Type | Example | Info | | ---------- | ------ | ------------------------------------ | ------------------------------------------------------------------------- | | user token | string | USER\_TOKEN\_1234567 | The userToken you provided in [setUserToken](/ios/load-sdk#set-usertoken) | | uid | string | 058c8716-47dd-4fc4-be89-00978a86b7c0 | The ID of your user on Gigastore | #### Sample Request ``` { "userToken": "USER_TOKEN_1234567", "customerUid": "058c8716-47dd-4fc4-be89-00978a86b7c0" } ``` ### Response Parameters | Attribute | Type | Example | Info | | --------- | ------ | ------------------ | ------------------------------------------------------------------ | | email | string | |

The email your user used to sign-in in your platform

| #### Sample Response ``` { "email": "email@domain.com" } ``` # UX Guide This UX guide is meant to help your team develop an eSIM App. \ It focuses on the user experience and interface components necessary for creating a seamless and intuitive interaction for end-users. This guide contains essential screens and components of the eSIM App. The components are outlined and linked to the API documentation page. By following this guideline, developers and designers can align their implementation with best practices in user experience. #### BUY DATA - Screen Flow This diagram illustrates the user's journey to purchase eSIM data within the app. It includes key screens such as the home screen, package selection, country coverage, checkout, payment, installation, and post-installation confirmation.
#### MANAGE DATA - Screen Flow This diagram illustrates the user journey for managing eSIM data. It includes screens for viewing eSIM details, selecting packages, checking coverage, making payments, and accessing support.
{% file src="/files/WWVuuUTC1fkqTFjWhBip" %} {% file src="/files/0hRW2o5Gb3M5yCIiwC5t" %} # Gigastore for Support Teams Gigastore provides Support Teams with a set of tools, designed to help deliver fast and effective customer service. The numbered list below shows where each element appears in the provided screenshots. Before proceeding, it is important to understand the following terms: \ • **Profile**: A profile is installed by the customer on their device. \ A customer can have multiple profiles.\ • **Package**: A package refers to the data plan associated with a profile. \ A customer can have multiple packages. \ Packages may be valid or expired, and they can either contain data or be empty. To access customer information, navigate to **Sales History** and search for the customer using ICCID or email. All previously sold packages will be displayed. Once a package is selected, the customer's information will be displayed on the screen. **Sold Data Package Section** This section provides the information related to the purchased package. **\[1] Date of Purchase** – The date when the package was bought. \ **\[2] Package Name** – A description of the package. \ **\[3] Volume** – The initial amount of GB included in the package. \ **\[4] Validity** – The initial number of days package is valid. \ **\[5] Purchase ID** – A unique identification number for the package. Each package has its own ID. This number will be needed in case of opening a ticket for Refund. \ **\[6] Package Status** – Can be **Purchased**, **Activated**, or **Refunded**. \ **\[7] Refund Button** – Allows to refund the customer. \[More information about refunds [here](https://www.notion.so/o/-MZDM6AnyY85i18ScRxP/s/-M_06ID1EGDSaSa9MhQE/~/changes/132/customer-support/package-refund/~/overview).]
**Attached Customer Profile Section** This section reflects summary of customer's profile. **\[1] Customer Profile link -** Opens page, displaying detailed information about customer's profile. \ **\[2] Customer Email** – Allows to add or update the customer’s registered email address. \ **\[3] Current Balance** – Reflects the total balance. A customer can have multiple packages, and this number shows **the total balance** across all packages. \ **\[4] Number of Profiles Attached** – Indicates how many profiles the customer has. \ **\[5] Country of Residency** – Allows to add or update the customer’s country of residency. \ **\[6] ICCID number** - Clickable field, provides additional information like last connection time and last connection country. \ **\[7]** **eSIM Status** – The possible statuses are: \ • **RELEASED** – Not installed on a device. \ • **DISABLED** – Installed, but the user has disabled the eSIM in the OS. \ • **INSTALLED** – Installed and enabled. \ • **ERROR** – An issue occurred during installation. \[[Contact support.](https://dent.app.link/e/ejsmhSb0wKb)] \ **\[8] Installation Link** – Opens page, displaying the QR code that can be shared with the customer.
**Customer Profile** **\[1] Current Balance** – Reflects the total balance. \ A customer can have multiple packages, and this number shows **the total balance** across all packages. **\[2] Install eSIM -** Provides QR code for the customer. \ **\[3] Package #1 information -** Expiration date, remaining balance, etc. for this package. \ **\[4] Package #2 information -** Expiration date, remaining balance, etc. for this package.\ **\[5] Installation Date** - The date when eSIM was installed last time.
# Connectivity This page describes how to troubleshoot the following connectivity issues that customers might encounter: 1. [eSIM configured incorrectly](#id-1.-esim-configured-incorrectly) 2. [Wrong APN](#id-2.-wrong-apn) 3. [Other issues](#id-3.-other-connectivity-issues) We recommend following these steps to ensure the correct function of the eSIM profile. ## 1. eSIM Configured Incorrectly First, check if the eSIM was successfully installed using the Gigastore API. If the eSIM is installed but shows No Service, ask the customer to perform the following steps and try to connect after each action: * Ensure roaming is switched on in the settings. * Turn off the WiFi and restart the device. * Turn off LTE mode/toggle to 3G, and restart the device. * Switch to manual network selection and try them one by one, restarting after each. * Remove the physical SIM for some minutes and try to trigger a connection using a browser, for example. * Please ensure the user has not added a phone number to their eSIM. Please note that on older iOS versions, the networks on the manual network selection might all be called DENT, but they are all individual networks. ## 2. Wrong APN At this point, the customer should have confirmed that the eSIM is installed and configured correctly. If the connection is still missing, the customer might have an APN that does not work in their country. An indicator could be that the device shows a connection, but no data can be consumed. The default APN global.telcoequity should work in most cases. Still, some operators might not have updated the settings yet. In those cases, it is worth trying to change the APN to establish a connection to the network. Ask the customer to change their APN to plus. If the user with plus APN complains about being located in Poland (IP) they can change the APN to global.telcoequity. ## 3. Other connectivity issues If the connection problem persists, the customer likely requires changes to their eSIM from our system. To find and fix the connection issues, please file a [**support ticket**](https://dent.app.link/e/ejsmhSb0wKb), so we can take a closer look at the case. Please add the following information to your request to speed up the support process: * Customer’s ICCID * Customer’s current country * Customer’s device OS * Customer’s device model (optional) * Further notes (optional) * Attached files, e.g., Screenshots (optional)
# Changing Device In order to use the eSIM on another device, it must be removed from the previous device first. Once it has been successfully removed, your system should show the status of the eSIM profile as “released”. Your App should now allow the user to repeat the installation process. (Please note that installations are limited to 5 times.) If your user has not removed the eSIM profile from the previous device and has no access to that device at the moment, please hand in a ticket with Support (naming the IMSI/ ICCID) for eSIM profile replacement. Once the profile has been replaced, it should show up as released again in your system. It will be available for your user via your App. # Package Refund Gigastore provides Credit Refunds for data packages if a customer cannot use the purchased package due to a technical issue. Refunds via Gigastore will be processed if all the following conditions are met: 1. **Package Purchase**: The package must have been purchased using Credits via Gigastore. 2. **Package Status**: The data package must still be valid (not expired) and unused (full data). 3. **Refund Limit**: You have not exceeded the maximum number of refunds allowed this month. To conduct a refund via Gigastore, please proceed to [Sales History](https://dent.giga.store/#/your-store/history), find the package the customer requested to Refund and click Refund.
The following statuses for the package are possible: 1. **Purchased**: The item was directly purchased and activated. It can be refunded. 2. **Activated**: The item was activated from inventory stock or purchased before December 6th, 2024.\ If the package has the status "Activated", it's not refundable via the Gigastore platform.\ Please open a [support ticket](https://dent.app.link/e/ejsmhSb0wKb) with our team, and make sure to include the Data Package ID. 3. **Refunded**: The item was purchased but refunded. If you need additional assistance, please open a [support ticket](https://dent.app.link/e/ejsmhSb0wKb) with our team.