Getting Started
The Getting Started Guide will show you how to setup your local development environment and create your first PDF document using a template with UniPDF in minutes.
At the end of this guide, you will know how to create a PDF report. You will also have a starter code that is extendable with other UniPDF capabilities.
What you’ll learn
- Create a UniCloud account
- Create your API Key
- Setup a local development environment
- Create your first PDF report
Prerequisites
- Have Go 1.20+ installed.
- A Linux, macOS or Windows machine.
- Familiarity with Golang. No worries, you don’t have to be an expert.
- Familiarity with using the command line.
Golang Version Compatibility
We are committed to providing the best experience for our users. As of now, we actively support the three latest versions of Go programming language. This ensures that you can leverage the latest features, enhancements, and security updates.
Current Supported Versions:
- Go 1.22
- Go 1.21
- Go 1.20
Create a UniCloud account
To use UniPDF, you need to sign up for a UniCloud account to get your API key. There are two types of licenses you can use with UniPDF.
License Types
Online License(API Key): The metered license is the most convenient way to get started with UniDoc products, and the Free tier is a great way to get started for free.
Offline License: Offline licenses are cryptography-based and contain full signed information verified based on signatures without making any outbound connections, hence the name “offline”. This license is suitable for users deploying OEM products to their customers or where there are strict restrictions on outbound connections due to firewalls and/or compliance requirements.
For this guide, we will be using the online metered API Key.
Navigate to UniCloud and create an account for a 30-day free trial.
Check your inbox for an activation email message from UniDoc. Copy the code and paste it into the browser to activate your account.
Access the developer dashboard
Once you have created a UniCloud account, you can sign in to the Developer Dashboard. The Developer Dashboard is a GUI-based platform where you can:
- Create your API Key - you will need this to authenticate your requests with our APIs. Remember to copy and keep the API key when you create one, as you can only see it once.
- Manage your Account Balance - Access to our APIs is charged yearly through a professional license or per request. We provide up to 100 free credits for a new account which you can top up anytime.
- Manage your account - You can update information and add team members to work in a shared space.
- Manage your activity logs - You can see the current activity logs on the account, especially when working in a team.
- View your payment history - Easily view your payment history.
- Manage support tickets - Create and view your support tickets for your team. This feature is available on a paid plan only.
Generate API Keys
From the UniCloud Dashboard, select API Key > click the +Add API Key button.
Enter a descriptive name for your API Key and click Save. Ensure you copy the generated API Key as you can only see it once.
Note: If you lose your API Key, you can always create a new one.
Setup your local development environment
Before working with the UniPDF library, you must set up your local development environment.
Create a project directory
Create a directory named unipdf-getting-started
mkdir unipdf-getting-started
Then, navigate into it.
cd unipdf-getting-started
Initialize a Go module/project.
go mod init unipdf-getting-started
Install the UniPDF SDK
Our UniPDF SDK is hosted on this Github repository. To install the Go SDK and its dependencies, run this command.
go get github.com/unidoc/unipdf/v3
Load the license API key
UniPDF authenticates every request you make with a valid API Key. For development, we recommend setting your API Key as an environment variable.
Linux/Mac
export UNIDOC_LICENSE_KEY=PUT_YOUR_API_KEY_HERE
Windows
set UNIDOC_LICENSE_KEY=PUT_YOUR_API_KEY_HERE
After setting the environment variables, UniPDF will automatically load the license key for subsequent API requests.
Create your first PDF Report
Let’s see the UniPDF SDK in action.
Import the SDK
Go ahead and create a file named first_pdf_report.go.
Import the necessary packages from the SDK into your project.
package main
import (
"github.com/unidoc/unipdf/v3/common/license"
"github.com/unidoc/unipdf/v3/creator"
)
The license package is included in every call to the SDK to authenticate your request with a valid license key. The creator package create new pages in a PDF. The model package is used to read and write PDF documents.
Import other dependencies
Our program will depend on their packages like os to read the environment variables, log to output a message to the terminal, usually error messages and time to include the time and date the document is created.
The updated import block will look like this:
package main
import (
"log"
"os"
"time"
"github.com/unidoc/unipdf/v3/common/license"
"github.com/unidoc/unipdf/v3/creator"
"github.com/unidoc/unipdf/v3/model"
)
Run the sample code
Add the following lines of code to the unipdf_getting_started file after the import block.
func init() {
// Make sure to load your metered License API key prior to using the library.
// If you need a key, you can sign up and create a free one at https://cloud.unidoc.io
err := license.SetMeteredKey(os.Getenv(`UNIDOC_LICENSE_API_KEY`))
if err != nil {
panic(err)
}
}
func main() {
c := creator.New()
c.SetPageMargins(50, 50, 100, 70)
helvetica, _ := model.NewStandard14Font("Helvetica")
helveticaBold, _ := model.NewStandard14Font("Helvetica-Bold")
p := c.NewParagraph("UniPDF")
p.SetFont(helvetica)
p.SetFontSize(48)
p.SetMargins(15, 0, 150, 0)
p.SetColor(creator.ColorRGBFrom8bit(56, 68, 77))
c.Draw(p)
p = c.NewParagraph("Example Page")
p.SetFont(helveticaBold)
p.SetFontSize(30)
p.SetMargins(15, 0, 0, 0)
p.SetColor(creator.ColorRGBFrom8bit(45, 148, 215))
c.Draw(p)
t := time.Now().UTC()
dateStr := t.Format("1 Jan, 2006 15:04")
p = c.NewParagraph(dateStr)
p.SetFont(helveticaBold)
p.SetFontSize(12)
p.SetMargins(15, 0, 5, 60)
p.SetColor(creator.ColorRGBFrom8bit(56, 68, 77))
c.Draw(p)
loremTxt := "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt" +
"ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut " +
"aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore" +
"eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt " +
"mollit anim id est laborum."
p = c.NewParagraph(loremTxt)
p.SetFontSize(16)
p.SetColor(creator.ColorBlack)
p.SetLineHeight(1.5)
p.SetMargins(0, 0, 5, 0)
p.SetTextAlignment(creator.TextAlignmentJustify)
c.Draw(p)
err := c.WriteToFile("hello_world.pdf")
if err != nil {
log.Println("Write file error:", err)
}
}
In this code, function init loads your license API Key from the environment variable you set earlier. The main function creates a page with three paragraphs styled as indicated in the code and saves it to a file named getting_started.pdf.
Note:
You are likely to see red lines underneath the code because some packages are yet to be installed.
To fix this, run go mod tidy to install the missing dependencies.
Save and run the file.
go run pdf_report.go
The created PDF will be added to your project directory. Open the getting_started_pdf in any PDF viewer. You should see a one-paged PDF like this.
Don’t have the time to set things up locally? Run the code in our online playground.
Next steps
Congratulations! You’ve successfully created your first PDF report with UniPDF.
It’s time for an adventure! Check out the rest of the UniPDF documentation, where you will find:
Practical step-by-step guides to help you achieve a goal.
Contains everything about the inner workings of the UniPDF SDK.