# 6. Developer Guide

The Developer Guide provides step-by-step instructions on how to integrate, extend, and customize the Ferdy Framework. This guide is tailored for developers building on top of Ferdy’s APIs and SDKs.

### **6.1 Getting Started**

1. Sign Up for API Access:
   * Visit the Ferdy Developer Portal.
   * Create a developer account and generate your API key.
2. Set Up the Environment:
   * Ensure all prerequisites are installed (Python, Node.js, Docker, etc.).
   * Download the Ferdy SDK for your preferred language or platform.
3. Basic Integration:
   * Use Ferdy APIs or SDKs to add core functionalities like conversational AI, task execution, or voice assistance to your app.

***

### **6.2 Ferdy SDK Integration**

#### **Web Integration**

The Ferdy JavaScript SDK is designed for web applications. It provides pre-built widgets and customizable components.

**Install SDK:**

`npm install ferdy-sdk`

**Basic Usage:**

`import { FerdyAPI } from 'ferdy-sdk';`

`const ferdy = new FerdyAPI({ apiKey: 'YOUR_API_KEY' });`

`async function getResponse(input) {`

  `const response = await ferdy.converse({ userId: '12345', input });`

  `console.log(response.response);`

`}`

`getResponse("What's the weather like today?");`

#### **Add Ferdy Widget:**

`import { FerdyWidget } from 'ferdy-sdk';`

`FerdyWidget.init({`

  `apiKey: 'YOUR_API_KEY',`

  `container: '#ferdy-chat',`

`});`

#### **Mobile Integration**

The Ferdy SDK for Android and iOS supports native and hybrid applications.

**Android:**

Add the Ferdy SDK to your build.gradle:\
implementation 'com.ferdy.sdk:android:1.0.0'

1. **Use the Ferdy API:**

`FerdyClient client = new FerdyClient("YOUR_API_KEY");`

`String response = client.converse("What's my schedule today?");`

`Log.d("FerdyResponse", response);`

2. **iOS:**

Add Ferdy SDK using CocoaPods:\
\
`pod 'FerdySDK', '~> 1.0'`

1. Use the Ferdy API:

`swift`\
`let client = FerdyClient(apiKey: "YOUR_API_KEY")`

`client.converse(input: "What's my schedule today?") { response in`

    `print(response)`

`}`<br>

***

### **6.3 Custom Workflows**

**Extending Task Execution:** Developers can create custom workflows using the Task Orchestration Engine.

**Define a New Workflow:**\
\
`{`

&#x20; `"workflow_name": "custom_task",`

&#x20; `"steps": [`

&#x20;   `{`

&#x20;     `"type": "API_CALL",`

&#x20;     `"endpoint": "https://example.com/task",`

&#x20;     `"method": "POST",`

&#x20;     `"data": {`

&#x20;       `"task_type": "email",`

&#x20;       `"email_body": "Hello, this is a test."`

&#x20;     `}`

&#x20;  `},`

&#x20;   `{`

&#x20;     `"type": "WAIT",`

&#x20;     `"duration": 5`

&#x20;   `},`

&#x20;   `{`

&#x20;     `"type": "NOTIFY",`

&#x20;     `"message": "Task completed successfully"`

&#x20;   `}`

&#x20;`]`

`}`

1. **Upload Workflow to Ferdy: Use the Ferdy CLI:**\
   \
   `ferdy-cli upload-workflow custom_task.json`
2. **Execute Workflow via API:**

POST /tasks/execute

`Authorization: Bearer YOUR_API_KEY`

`Content-Type: application/json`

**Body:**\
\
`{`

&#x20; `"workflow_name": "custom_task",`

&#x20; `"parameters": {`

&#x20;   `"email": "user@example.com"`

&#x20; `}`

`}`<br>

***

### **6.4 Customizing the UI**

Ferdy provides customizable widgets for conversational AI and task management.

**Default Widget:**

`<div id="ferdy-chat"></div>`

`<script src="https://cdn.ferdy.ai/sdk.js"></script>`

`<script>`

&#x20; `FerdyWidget.init({`

&#x20;   `apiKey: 'YOUR_API_KEY',`

&#x20;   `container: '#ferdy-chat',`

&#x20;   `theme: 'dark',`

&#x20; `});`

`</script>`

**Custom Styling:**

`#ferdy-chat {`

&#x20; `border: 2px solid #000;`

&#x20; `border-radius: 10px;`

&#x20; `width: 400px;`

&#x20; `height: 600px;`

`}`

***

### **6.5 Testing and Debugging**

1. **Enable Debug Mode:** Pass debug: true in the SDK configuration to log API calls and errors.
2. **API Testing with Postman:** Import the Ferdy API collection from the Developer Portal to test endpoints.
3. **Error Handling:**
   * **Common Errors:**
     * **401 Unauthorized:** Verify API key or token.
     * **400 Bad Request:** Check request parameters.

Use the error object in API responses for details:\
\
`{`

&#x20; `"error": {`

&#x20;   `"code": 400,`

&#x20;   `"message": "Invalid input format."`

&#x20; `}`

`}`<br>

***

### **6.6 Extending Ferdy with Plugins**

Ferdy allows developers to build and integrate plugins for custom functionality.

1. **Plugin Structure:**

**Manifest File** (plugin.json):\
\
`{`

&#x20; `"name": "My Custom Plugin",`

&#x20; `"version": "1.0",`

&#x20; `"entry_point": "index.js",`

&#x20; `"permissions": ["task_execution", "data_storage"]`

`}`<br>

**Entry Point** (index.js):\
\
`module.exports = {`

&#x20; `executeTask: async (params) => {`

&#x20;   `console.log("Executing custom task with params:", params);`

&#x20;   `return { status: "success" };`

&#x20; `}`

`};`<br>

2. R**egister Plugin:**

Upload the plugin via the Developer Portal or Ferdy CLI:\
`ferdy-cli register-plugin my-plugin.zip`

**Invoke Plugin:** Use the API to trigger the plugin:\
`POST /plugins/my-custom-plugin/execute`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://feeda.gitbook.io/ferdy-framework/6.-developer-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.