# Installation

{% hint style="danger" %}
**Critical Prerequisites:**

* Use [WinSCP](https://winscp.net/eng/download.php) for FTP file transfers. FileZilla may corrupt files during transfer.
* If upgrading from v1 to v2, you **must** remove all `gksphone_*` tables from your database before proceeding.
  {% endhint %}

{% embed url="<https://www.youtube.com/watch?v=06a9iddaCrw>" %}
Installation Video Tutorial
{% endembed %}

## Step 1: File Structure Setup <a href="#step-1-file-structure" id="step-1-file-structure"></a>

Create the proper directory structure for GKSPHONE V2:

1. Navigate to your server's resources folder
2. Create a `[phone]` folder inside the resources directory
3. Extract all files from the downloaded zip into this `[phone]` folder

**Expected Directory Structure:**

```
resources/
└── [phone]/
    └── gksphone/
        ├── config/
        ├── client/
        ├── server/
        └── ...
```

<figure><img src="https://1859156681-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft4ljavSyu0jJXdm0X9Pd%2Fuploads%2FbrXBXeyFQtwxLmPgwhpk%2Fimage.png?alt=media&#x26;token=7ff521ae-d811-4eec-990e-7caae02fbd57" alt="Phone folder structure"><figcaption><p>Create [phone] folder in resources</p></figcaption></figure>

## Step 2: Item Configuration <a href="#step-2-items" id="step-2-items"></a>

Configure phone items based on your inventory system:

{% tabs %}
{% tab title="QB Inventory" %}
Add these items to your `qb-core/shared/items.lua` file:

```lua
-- Phone Items
phone = {
    name = 'phone',
    label = 'Phone',
    weight = 700,
    type = 'item',
    image = 'phone.png',
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = 'Neat phone ya got there'
},

iphone = {
    name = 'iphone',
    label = 'iPhone',
    weight = 1000,
    type = 'item',
    image = 'iphone.png',
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = 'Very expensive phone'
},

-- Powerbank Item (Optional)
powerbank = {
    name = 'powerbank',
    label = 'Powerbank',
    weight = 200,
    type = 'item',
    image = 'powerbank.png',
    unique = true,
    useable = true,
    shouldClose = true,
    combinable = nil,
    description = 'To charge the phone'
},
```

{% endtab %}

{% tab title="OX Inventory" %}
{% hint style="info" %}
Add the following to `ox_inventory/data/items.lua`. If you already have phone or iphone items, replace them with this data.
{% endhint %}

```lua
["phone"] = {
    label = "Phone",
    weight = 190,
    stack = false,
    consume = 0,
    client = {
        export = "gksphone.UsePhoneItem",
        remove = function()
            TriggerEvent("gksphone:client:ItemRemoved", "phone")
        end,
        add = function()
            TriggerEvent("gksphone:client:ItemAdded", "phone")
        end
    }
},

["iphone"] = {
    label = "iPhone",
    weight = 190,
    stack = false,
    consume = 0,
    client = {
        export = "gksphone.UsePhoneItem",
        remove = function()
            TriggerEvent("gksphone:client:ItemRemoved", "iphone")
        end,
        add = function()
            TriggerEvent("gksphone:client:ItemAdded", "iphone")
        end
    }
},

-- Powerbank Item (Optional)
["powerbank"] = {
    label = "Powerbank",
    weight = 190,
    stack = false,
    consume = 0,
    server = {
        export = "gksphone.powerbank"
    }
},
```

{% endtab %}

{% tab title="Tgiann Inventory" %}
{% hint style="info" %}
Add the following to `tgiann-iventory/items/items.lua`. If you already have phone or iphone items, replace them with this data.
{% endhint %}

```lua
["phone"] = {
    name = "phone",
    type = "item", 
    label = "Phone",
    weight = 190,
    consume = 0,
    useable = true,
    unique = true,
    shouldClose = true, 
    client = {
        export = "gksphone.UsePhoneItem"
    }
},

["iphone"] = {
    name = "iphone",
    type = "item", 
    label = "iPhone",
    weight = 190,
    consume = 0,
    useable = true,
    unique = true,
    shouldClose = true, 
    client = {
        export = "gksphone.UsePhoneItem"
    }
},

-- Powerbank Item (Optional)
["powerbank"] = {
    name = "powerbank",
    label = "Powerbank",
    weight = 190,
    stack = false,
    consume = 1,
    client = {
        event = "gksphone:client:powerbank"
    }
},

```

Add iphone and phone to `tgiann-inventory/configs/configMaxStack.lua` for stack

```lua
config.maxStacks = {
    iphone = 1,
    phone = 1
}
```

{% endtab %}

{% tab title="ESX" %}
ESX includes a default phone item. Add only the iPhone item by running this SQL query:

```sql
INSERT INTO `items` (`name`, `label`) VALUES ('iphone', 'iPhone');
```

{% endtab %}

{% tab title="Custom" %}
Review the documentation for [Custom Inventory](https://docs.gkshop.org/gksphone-v2/configuration/custom-inventory-1).
{% endtab %}
{% endtabs %}

## Step 3: Database Setup <a href="#step-3-database" id="step-3-database"></a>

{% hint style="danger" %}
Before running the SQL file, make sure to delete all tables starting with `gksphone_` in your database.
{% endhint %}

{% hint style="success" %}
**Automatic Setup Available:** If you enable `Config.DatabaseAutoSetup` in `gksphone/config/config.lua`, the system will automatically create the required database tables. You can skip the manual SQL step.
{% endhint %}

#### Manual Database Setup

1. **Important:** Delete all existing `gksphone_*` tables from your database
2. Run the `gksphone/gksphonev2.sql` file in your database management tool

{% embed url="<https://www.youtube.com/watch?v=40rEUkF2mso>" %}
Database Setup Tutorial
{% endembed %}

## Step 4: Framework Configuration <a href="#step-4-framework" id="step-4-framework"></a>

{% hint style="info" %}
**Supported Frameworks:** ESX, QB-Core, Qbox There is also a standalone file that you can customize for your own framework.
{% endhint %}

{% hint style="success" %}
If you haven't changed your framework's source file name, you can leave this as `"auto"` for automatic detection.
{% endhint %}

1. Open `gksphone/config/config.lua`
2. Set `Config.Framework` to match your server framework:
   * `"esx"` for ESX
   * `"qb"` for QB-Core
   * `"qbx"` for Qbox
   * `"auto"` for automatic detection

<figure><img src="https://1859156681-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft4ljavSyu0jJXdm0X9Pd%2Fuploads%2FqmFkbjZtULmsJFuyHejT%2Fimage.png?alt=media&#x26;token=e351661f-5517-4a8e-a12e-58854650a189" alt="Framework configuration"><figcaption><p>Configure framework in gksphone/config/config.lua</p></figcaption></figure>

## Step 5: Server Configuration <a href="#step-5-serverconfig" id="step-5-serverconfig"></a>

Configure your server settings in `gksphone/config/serverconfig.lua`:

### Media Service Setup

You can use any media service you prefer. We recommend GKS Media, Fivemerr, or Fivemanage.

{% hint style="info" %}
If you are having trouble taking a photo, you may have filled out the fields below incorrectly.
{% endhint %}

{% code title="serverconfig.lua" %}

```lua
-- Available options: "fivemanage", "gksmedia", "customMedia" 
Cfg.MediaService = ""

-- Authentication tokens for your chosen service
Cfg.AuthTokenImage = ""    -- Image upload token/API key
Cfg.AuthTokenAudio = ""    -- Audio upload token/API key
Cfg.AuthTokenVideo = ""    -- Video upload token/API key
```

{% endcode %}

### Music and PlayTube App Configuration

{% hint style="info" %}
You must enter your GKSPHONE purchase transaction ID in `Cfg.TebexTransactionID` in the serverconfig.lua file. If you don't know your transaction ID, check your [Tebex purchase history](https://checkout.tebex.io/payment-history/login).
{% endhint %}

<figure><img src="https://1859156681-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft4ljavSyu0jJXdm0X9Pd%2Fuploads%2FpsoNl4AO2iYaQ0NmOsFQ%2Fimage.png?alt=media&#x26;token=971b5104-ad5c-4cd7-b5a2-2e4590392956" alt="Tebex configuration"><figcaption><p>Configure Tebex ID in gksphone/config/serverconfig.lua</p></figcaption></figure>

{% hint style="warning" %}
**Important:** Keep your Tebex ID secure. Support cannot help recover lost transaction IDs.
{% endhint %}

### Application Logging Configuration

{% hint style="info" %}
**Discord Webhooks:** Enter Discord webhook URLs for applications you want to log in the serverconfig.lua file.

**Fivemanage Logs:** Ensure [fmsdk](https://github.com/fivemanage/sdk/releases/latest) is installed for Fivemanage logging support.
{% endhint %}

<figure><img src="https://1859156681-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft4ljavSyu0jJXdm0X9Pd%2Fuploads%2FgJZYt2xwcjq71abn43AF%2Fimage.png?alt=media&#x26;token=f0240ae3-f3d5-4ed0-9941-62a48d8e02ea" alt="Logging configuration"><figcaption><p>Configure logging in gksphone/config/serverconfig.lua</p></figcaption></figure>

## Step 6: Server Startup Configuration <a href="#step-6-server-cfg" id="step-6-server-cfg"></a>

Add GKSPHONE to your `server.cfg` file. **Order is important** - ensure dependencies start before the phone system:

```cfg
# Core Framework (Required first)
ensure pma-voice
ensure oxmysql
ensure es_extended  # or qb-core

# Dependencies (Must start before phone)
ensure your_eyetarget
ensure your_banking
ensure your_inventory
ensure your_housing
ensure your_garages

# Other scripts can start before or after phone
ensure other_scripts

# Phone System (Start last)
ensure [phone]
```

{% hint style="success" %}
**Installation Complete!** After completing all steps, restart your server. The GKSPHONE V2 system should now be active and ready for use.
{% endhint %}

## 🔄 Updating GKSPHONE V2

Follow the steps below to safely update your GKSPHONE resource:

{% stepper %}
{% step %}

#### 📦Backup Your Current Installation

Before updating, create a backup of your current `gksphone` folder.\
We recommend compressing it into a `.zip` file for safe storage.
{% endstep %}

{% step %}

#### 🗑️ Remove the Old Version

Delete the existing `gksphone` folder from your server's `[phone]` directory.
{% endstep %}

{% step %}

#### ⬇️ Download the Latest Version

Download the latest version of GKSPHONE V2 from the [portal cfx](https://portal.cfx.re/assets) page.
{% endstep %}

{% step %}

#### ⚙️ Reapply Your Configurations

If you've made custom changes to the following files:

* `gksphone/config/config.lua`
* `gksphone/config/serverconfig.lua`

Make sure to reapply your edits after updating.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
💡 Tip: Keep a copy of your edited config files before deleting the old version, so you can easily compare and merge changes.
{% endhint %}

## 📱 Migrating from Other Phones

This guide explains how to migrate data from other popular phone systems to **GKSPhone**.\
Currently, migration is only supported for **LB-Phone**.\
Support for other phones will be added in future updates.

### 🔄 What Data is Transferred

When migrating from **LB-Phone**, the following data will be transferred to **GKSPhone**:

* 📞 Call History
* 👤 Contacts
* 🖼️ Photos
* 🗒️ Notes
* 📰 Advertisement Posts
* 🕶️ DarkChat
* 📸 Instagram
* 🐦 Twitter
* 💬 Messages

All these data types are automatically converted and imported into the **GKSPhone** database.

### ⚙️ Requirements

Before running the migration process:

1. Make sure your **GKSPhone database is clean** (no existing data).
2. Ensure **no players are online** on your server during the transfer.

### 🚀 Migration Process

Once you meet the above requirements:

1. Open your **server console**.
2. Run the following command:

   ```
   migratephone
   ```
3. Wait until the process completes.\
   Do **not** restart or stop the server during this process.

After completion, all eligible player data from **LB-Phone** will be migrated to **GKSPhone** automatically.

### 🧩 Future Support

Migration tools for other popular phone systems will be added in future updates.\
Stay tuned for announcements in our Discord or documentation.