Use Guide

Adding Google Spreadsheet as a data source

You can use any number of documents as a data source for your project. Here are a few simple steps that allow you to add a document

1) Open the plugin settings from the Unity editor menu

2) Create a Google Spreadsheet document by clicking “Add new Spreadsheet”. Enter the document name. This name will be used as a document id in your project. it doesn't have to do much with the real document name.


3)  Fill Spreadsheet public key field key.


4) Make sure that the Spreadsheet visibility options under the document sharing settings are Public on the web or Anyone with the link.

Click the “Update ” button to retrieve document data to the cash file. Every time you want to grab new data from the document you can update the cache  using Update or Update All data.


That is it, the data is now inside your project and can be accessed via the Editor or the Scripting API

Note: Every document has a timestamp with the time when it was changed. The timestamp is displayed next to  the document name.


Warning:  All the document lines should have some data or Google Request API will simply ignore these rows. Unfortunately, this is how the API works. You can just look at  the example document to understand what that means.


You can also use Spreadsheet pages as different data sources. Instead of using different spreadsheets. To register a page in an associated document just follow these simple steps below:

  • Open the page in google spreadsheet that you want to add
  • Copy worksheet  grid   
  • Click Add new Worksheet in the document settings.
  • Paste grid to the Worksheet ID field, and enter the Worksheet Name. This name will be used as the worksheet id in your project. it doesn't  have to be related to the real document name.


Connecting Spreadsheet values using the Editor.

    You can connect data from spreadsheet cells to any field of your MonoBehaviour script. Data can be connected to any field if it is a field with type:

  • string, int, float, long
  • <supported_type>[],
  • List<supported_type>
  • Dictionary<supported_type, supported_type>

Data retrieval is recursive.  For example, Vector3 class is the serializable class with x, y, z float fields - you can connect data to these fields. The same applies to  your own scripts. Here is how the editor data connection looks like:

Here are the simple steps on how to connect data to fields with type: string, int, float, long. We will use GD_ExampleDataScript as an example. The script contains public string MyString; filed. Letch attaches GD_ExampleDataScript and  GoogleData scripts to the same game object.

1) Press the “Add new connection” button and select GD_ExampleDataScript and worksheet (Optional).


2) Press “Attach Filed” and choose MyString filed.


3) In field data delegate settings choose data source.

4) Specify Cell key in Worksheet, e.g. 'A1'.


The same actions for data types: 

 string, int, float, long.

Retrieving arrays is similar. Let’s use the same game object and script. The Script contains public float[] MyFloatArray filed. To fill the array press  “Attach Filed” and choose MyFloatArray filed. The data delegate setting is a bit different. Here are explanations for each of them

  1. Direction. Array data direction. we can choose between row or col direction.
  2. Start Cell. This is a cell key with the first element of our array.
  3. Use link break. Enables fixed line length.
  4. Range Length. Quantity of element before we will jump on next row / col

The same actions for data types:  

string[], int[], float[], long[], List<string>, List<int>, List<float>, List<float>.

And the last one, is Dictionaries. Let’s use the same game object and (or is as a script type? script. This Script contains public Dictionary<string, long> MyDictionary filed. To fill the dictionary press  “Attach Filed” and choose MyDictionary filed. The data delegate setting is described below.

  1. Direction, Start Cell, Use link break, Range Length - similar to the array.
  2. Column Shift. Value column shifts regarding key column.
  3. Row Shift. Value row shifts regarding key row.


The same actions for data types:  

Dictionary<string, string>,  Dictionary<string, int>,  Dictionary<string, long>, Dictionary<string, float>.
Dictionary<int, string>,  Dictionary<int, int>,  Dictionary<int, long>, Dictionary<int, float>.
Dictionary<long, string>,  Dictionary<long, int>,  Dictionary<long, long>, Dictionary<long, float>.
Dictionary<float, string>,  Dictionary<float, int>,  Dictionary<float, long>, Dictionary<float, float>.


Retrieving Spreadsheet data with encryption.

This chapter will describe how to retrieve data from spreadsheets using C# scripting in unity. You can use this API in the Editor and in Runtime as well. All the described code samples can be found in DocDataRertivalExamle script.

Here is a code example for when we need to retrieve string data  from A1 cell. We will use our GoogleDocConnectorExample spreadsheet as the data source. The A1 cell contains ‘Spawner1 Settings’ value. We can specify the data cell in a few different ways, you can see the code example below.

string val;
string DOC_NAME = "Google Doc Connector Example";

//Using cell col / row indexes
val = GoogleDocAPI.GetValue<string>(DOC_NAME, 1, 1);

//Using GDCell class with col / row indexes
GDCell cell =  new GDCell(1, 1);
val = GoogleDocAPI.GetValue<string>(DOC_NAME, cell);

//Using GDCell class with key representation
cell =  new GDCell("A1");
val = GoogleDocAPI.GetValue<string>(DOC_NAME, cell);


The Code example for how to retrieve selected range from  GoogleDocConnectorExample spreadsheet  as List<int>.



//Retriving data range into list<int>

List<int> array;
GDCellRange range =  new GDCellRange();
range.StartCell =  new GDCell("C11");
range.useLinebreak = true;
range.LineLength = 3;

array = GoogleDocAPI.GetList<int>(DOC_NAME, range);
//Printing list values
foreach (int data in array) {
Debug.Log("List Data: " + data);