# Example Project

## Prerequisites

* Latest version of Xcode (`14.3` as of writing)
* A Discord bot and its token - follow [#creating-a-discord-bot](#creating-a-discord-bot "mention") for detailed instructions on creating a bot in Discord's developer portal

### Creating a Discord Bot

By following these instructions, you'll register your very own Discord bot. Obviously, these steps assume you have a Discord account.

1. Go to Discord's [Developer Portal](https://discord.com/developers/applications)
2. Press the **New Application** button to start creating an application

   <figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2FRUKyPdbrlJ6VjmoRkNYp%2FScreenshot%202022-12-14%20at%207.30.48%20PM.png?alt=media&#x26;token=abc3ce24-ff5f-4601-bdaa-2625d017552c" alt=""><figcaption><p>A portal... for developers?</p></figcaption></figure>
3. Enter a totally not overused name for your application (you can set a different name for your bot later), then hit the inviting **Create** button

   <figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2F0UaCUeXoRIudQags6Gns%2FScreenshot%202022-12-14%20at%207.31.48%20PM.png?alt=media&#x26;token=1673b358-7301-4994-aba8-110ac7fd7f61" alt=""><figcaption><p>ToS? What ToS?</p></figcaption></figure>
4. Go to the **Bot** section of your new application, and click **Add Bot**

   <figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2FqY0kySRbkGC4TIDrArva%2FScreenshot%202022-12-14%20at%207.33.39%20PM.png?alt=media&#x26;token=6b45d06a-f8fe-4ebf-bd8b-faa8a07e98da" alt=""><figcaption><p>"robots are too cool to destroy" they said</p></figcaption></figure>
5. After your bot's created, you could change its Discord username (if required). We'll be keeping all other options at their defaults for now.
6. Press the **Reset Token** button, enter your OTP if/when requested, and copy the token (as shown below). You might want to save it somewhere, or just keep it in your clipboard.

   <figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2FwajdpRwKIlVGeyGGEGBo%2FScreenshot%202022-12-14%20at%207.35.14%20PM.png?alt=media&#x26;token=e11eeb3d-ff84-424f-bc05-463bc2436d71" alt=""><figcaption><p>Don't worry, if you're reading this, that token is no longer valid</p></figcaption></figure>
7. In the sidebar, go to **OAuth2** > **URL Generator** to get a URL to add your bot to a server. Select the **bot** scope and ensure (at least) the **Send Messages** permission is enabled. Refer to the screenshot below for the checkboxes that you'll need to check (many options have been removed to fit everything in one page).

   <figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2FKnXyAJd5RlKeRVvcGsSj%2FScreenshot%202022-12-14%20at%207.59.11%20PM.png?alt=media&#x26;token=896ce077-3aad-42da-99f8-3a69ade7c473" alt=""><figcaption><p><em>hmm</em> the options be looking a little off</p></figcaption></figure>

   Visit the **Generated URL** and follow the authorisation flow to add the bot to a server.
8. With the bot token and ID of the server you added the bot to, continue with the steps below

## Cloning the Example Project

If you'd like an example to get you started, fret not! Simply fork the [DiscordKitBotDemo](https://github.com/SwiftcordApp/DiscordKitBotDemo) repository by hitting the inviting **Fork** button on the top right. (The exampe project only works with Xcode right now, sorry!)

<figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2FKXxf3CNY0DEr20B77kRE%2FScreenshot%202022-12-14%20at%201.30.41%20PM.png?alt=media&#x26;token=65569020-b404-4475-a7ea-96b5d72bf872" alt=""><figcaption></figcaption></figure>

Then, in the **Welcome to Xcode** window, use the **Clone an existing project** action and provide the URL to your repository.&#x20;

## Configuration

Resist the urge to hit ▶️ just yet, for you'll need to configure the project for your bot first!

1. Create a new **Configuration Settings File** in the Xcode project and add the following line (as shown in the image below):

   `TOKEN=<your-discord-token>`

   <figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2FXm2r6wM64jnxXkF7bc50%2FScreenshot%202022-12-14%20at%201.44.04%20PM.png?alt=media&#x26;token=423f4300-293b-4195-b377-415972f18402" alt=""><figcaption></figcaption></figure>

   *Note: The name of the `.xcconfig` file doesn't matter, it'll work as long as it's added to your app's target.*
2. Ensure your bot is added to a server and minimally has the **Send Messages** permission
3. Copy the ID of that server and set it as the value of the `COMMAND_GUILD_ID` environment variable in the **DiscordKitDemo** target

   <figure><img src="https://1903821505-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWJuHiYLW9jKqPb7h8D7t%2Fuploads%2FLqf2RqUvVzl0LUB5T6X6%2FScreenshot%202022-12-14%20at%201.48.12%20PM.png?alt=media&#x26;token=f29029f6-4e16-420f-af09-f700565bf20e" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
If you're using a version control system such as Git, ensure the `.xcconfig` file is **never added to version control** by adding an entry in `.gitignore` or similar. This ensures you never accidentally expose your token on GitHub or such.\
If you're using Git, you can do so by adding the following line to your `.gitignore` file (create one if it doesn't already exist):

```
*.xcconfig
```

{% endhint %}

Now that's all done, go ahead to build and run the project! If everything goes well, you'll see several slash commands registered in the server that you set in step 3. Go ahead and try them out, and you've just ran your first Swift Discord bot powered by DiscordKit!