magnitudegatewaygoogle analyticsadapter userguide · magnitude gateway google analytics adapter...

Magnitude Gateway GoogleAnalytics Adapter

User Guide

Magnitude Software, Inc.

Version 1.6.13April 6, 2020

Copyright © 2020 Magnitude Software, Inc. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, ortransmitted, in any form or by any means, electronic, mechanical, photocopying,recording, or otherwise, without prior written permission from Magnitude.

The information in this document is subject to change without notice. Magnitude strivesto keep this information accurate but does not warrant that this document is error-free.

Any Magnitude product described herein is licensed exclusively subject to theconditions set forth in your Magnitude license agreement.

Magnitude, the Magnitude logo, and Magnitude Software, Inc. are registeredtrademarks of Magnitude Software, Inc. in Canada, the United States and/or othercountries.

All other company and product names mentioned herein are used for identificationpurposes only and may be trademarks or registered trademarks of their respectiveowners.

Information about the third-party products is contained in a third-party-licenses.txt filethat is packaged with the software.

www.simba.com 2

User Guide

About This Guide

PurposeThe Magnitude Gateway Google Analytics Adapter User Guide describes theconnection properties that must be set in order for the adapter to successfully connectto Google Analytics. This guide also provides detailed information about the following:

l The connection properties that are supported by the adapter.l The accepted syntax for connection strings and connection URLs, includingexamples of strings and URLs for connecting to Google Analytics.

AudienceThe guide is intended for users who are configuring the Magnitude Gateway GoogleAnalytics Adapter to connect to and retrieve data from Google Analytics, and needdetailed information about the supported connection properties and connection stringand URL syntaxes. It is assumed that the Magnitude Gateway Google AnalyticsAdapter has already been installed and set up for use.

Knowledge PrerequisitesWhen using the Magnitude Gateway Google Analytics Adapter, the followingknowledge is helpful:

l Familiarity with Google Analytics data.l Familiarity with using your ODBC or JDBC application to connect to datasources.

l Familiarity with the GDSN and DSN configuration processes described in theMagnitude Gateway User Guide.

Document ConventionsItalics are used when referring to book and document titles.

Bold is used in procedures for graphical user interface elements that a user clicks andtext that a user types.

Monospace font indicates commands, source code, or contents of text files.

www.simba.com 3

User Guide

Note:

A text box with a pencil icon indicates a short note appended to a paragraph.

Important:

A text box with an exclamation mark indicates an important comment related to thepreceding paragraph.

www.simba.com 4

User Guide

Table of Contents

About theMagnitudeGatewayGoogle Analytics Adapter 6Using theMagnitudeGateway Google Analytics Adapter 6

Connecting to Google Analytics 8Specifying Connection Properties 10

Writing Connection Strings and URLs for Google Analytics 12Examples: Connecting to Google Analytics Using aGDSN 13Examples: Connecting to Google Analytics Using aGDSN and Additional Properties 16Examples: Connecting to Google Analytics Using a DSN and Additional Properties 17Examples: Connecting to Google Analytics Without Using GDSNs or DSNs 18

Google Analytics Connection Properties 25Key Names of Google Analytics Connection Properties 25Primary Connection Properties 27Proxy Connection Properties 31SSLConnection Properties 33Optimizations Connection Properties 35

Google Analytics Stored Procedures 37

Google Analytics Schema Tables 38

Third-Party Trademarks 39

www.simba.com 5

User Guide

About the Magnitude Gateway Google AnalyticsAdapter

The Magnitude Gateway Google Analytics Adapter enables streamlined analytics andreporting on Google Analytics data. Complying with both the ODBC 3.80 and JDBC4.2 data standards, the adapter simplifies the process of connecting to data sources byenabling you to use the same connection across both types of applications. OnWindows and macOS, the adapter is supported by two additional applications:

l The Magnitude Gateway Settings application provides an intuitive user interfacedesigned to simplify the process of configuring adapters and definingconnections.

l The Connection Assistant application further simplifies the connection processby conveniently providing ODBC connection strings and JDBC connection URLsfor all connections that were configured through Magnitude Gateway Settings. Italso enables streamlined support for OAuth authentication processes.

The adapter returns Google Analytics data through specially generated schema tables,which map the data to a traditional relational format that is compatible with ODBC andJDBC applications. When you connect to Google Analytics using an ODBCapplication, the adapter also provides stored procedures that enable you to easilymanipulate the data without designing and executing complex query statements. For acomplete reference guide to the database schema tables and stored procedures usedby the adapter, see the Magnitude Gateway Google Analytics Adapter ReferenceGuide.

Using the Magnitude Gateway Google AnalyticsAdapterTo set up and use the adapter, do the following:

1. Install Magnitude Gateway. Choose the edition of the product that best meetsyour deployment and usage requirements. For more information, see thefollowing documentation:

l Magnitude Gateway Desktop Installation Guidel Magnitude Gateway Embedded Edition Installation and ConfigurationGuide

2. Install the adapter and provide a valid copy of its license. For more information,see the following documentation:

l If you have installed the desktop edition of the product, see "Setting UpLocal Adapters" in the Magnitude Gateway User Guide.

www.simba.com 6

User Guide About the Magnitude Gateway GoogleAnalytics Adapter

l If you have installed the embedded edition of the product, see "Setting UpAdapters" in the Magnitude Gateway Embedded Edition Installation andConfiguration Guide.

3. Specify connection properties to define a connection to Google Analytics. Formore information, see Connecting to Google Analytics on page 8.

4. In your ODBC or JDBC application, use the connection that you defined in theprevious step to access your Google Analytics data. For information about how touse a DSN, connection string, or connection URL in your application, see theproduct documentation for that application.

www.simba.com 7

User Guide About the Magnitude Gateway GoogleAnalytics Adapter

Connecting to Google Analytics

To connect to Google Analytics using the Magnitude Gateway Google AnalyticsAdapter, you must provide connection information such as which specific data sourceto connect to and how to handle the data that is accessed during the connection. Youprovide this information by specifying connection properties. For more information, seeSpecifying Connection Properties on page 10.

The Magnitude Gateway Google Analytics Adapter is designed to connect to theGoogle Analytics web service, and retrieve the data from the Google Analyticsapplication that is authenticated by a given access token. To successfully connect toGoogle Analytics, at minimum you must provide either the access token, or a client IDand client secret that enables the adapter to obtain and use the access token.

Note:

l We recommend that you connect to Google Analytics using a client ID andclient secret instead of using an access token. Access tokens expire after acertain amount of time, potentially causing connections to stop workingunexpectedly. When you connect using the client ID and secret, the adapteralways retrieves a valid access token at connection time.

l If you need an access token, on Windows or macOS you can use theConnection Assistant to retrieve one. For more information, see theMagnitude Gateway User Guide. Alternatively, business intelligence toolsoften provide a dialog box that enables you to retrieve an access token usingyour credentials.

The Google Analytics application that you are connecting to must use a redirect URI.Otherwise, the adapter cannot authenticate the connection to Google Analytics. Toprovide the redirect URI, access your application settings through the Google APIConsole, and, in the Authorized Redirect URIs field, specify the redirect URI used bythe adapter.

To connect to Google Analytics using a client ID and client secret, specify theseproperties:

Property Name Key Name

Authentication Method Auth_Type

Client ID Auth_Client_ID

www.simba.com 8

User Guide Connecting to Google Analytics


Client Secret Auth_Client_Secret

Scopes Auth_Scope

Redirect URI Auth_BaseRedirectUri

Or, to connect to Google Analytics using an access token, specify these properties:



Access Token Auth_AccessToken

Note:

Each connection property is identified by a property name as well as a key name.Property names are displayed in the Magnitude Gateway Settings user interface.Key names are used in DSNs, connection strings, and connection URLs.

For a complete summary of how the property names and key names supported bythe Magnitude Gateway Google Analytics Adapter are mapped to each other, seeKey Names of Google Analytics Connection Properties on page 25.

Some scenarios require you to also specify the following properties, as describedbelow:

Scenario Property Name Key Name

You are creating aGDSN in MagnitudeGateway Settings.

Name N/A

You are connectingto Google Analyticsthrough a proxyserver that does notrequire you to log in.

Proxy Host ProxyHost

Proxy Port ProxyPort

www.simba.com 9


Scenario Property Name Key Name

You are connectingto Google Analyticsthrough a proxyserver that requiresyou to log in.



Proxy User ID ProxyUid

Proxy Password ProxyPwd

You are using aWindows computerconnect to GoogleAnalytics through aproxy server, andthe proxy serverinformation can beretrieved throughthe Internet Optionsin Internet Explorer.

Use Windows ProxySettings

UseWindowsProxySettings

For detailed information about all the connection properties that the MagnitudeGateway Google Analytics Adapter supports, see Google Analytics ConnectionProperties on page 25.

Specifying Connection PropertiesTo specify connection properties, you can do any of the following:

l Create a Gateway Data Source Name (GDSN) using MagnitudeGateway Settings.GDSNs are data structures that store connection informationfor use in both ODBC and JDBC applications. For more information, see"Configuring GDSNs" in the Magnitude Gateway User Guide.

Note:

GDSNs cannot be used directly in ODBC and JDBC applications. To use aGDSN, create an ODBC Data Source Name (DSN), ODBC connectionstring, or JDBC connection URL that refers to the GDSN. Then, use thatDSN, string, or URL in the application.

l Create a DSN using the ODBC Data Source Administrator. DSNs are datastructures that store connection information for use in ODBC applications. You

www.simba.com 10


must configure the DSN to refer to an existing GDSN, but you can also specifyadditional connection properties in the DSN. For more information, see "CreatingODBC DSNs" in the Magnitude Gateway User Guide.

l Write an ODBC connection string or JDBC connection URL. Connectionstrings are specially formatted lines of text that are used to specify connectioninformation in ODBC applications. Connection URLs serve the same purpose,but for JDBC applications. You can write a string or URL that specifies a GDSN,a DSN (for ODBC connections only), a set of connection properties, or acombination of these. For more information, see Writing Connection Strings andURLs for Google Analytics on page 12.

For detailed information about the connection workflows that Magnitude Gatewaysupports, see "Connecting to Your Data" in the Magnitude Gateway User Guide.

www.simba.com 11


Writing Connection Strings and URLs for GoogleAnalytics

A connection string is a specially formatted line of text that specifies connectioninformation in a format that can be used in ODBC applications. A connection URLserves the same purpose, but for JDBC applications. You can write a string or URLthat specifies the necessary connection information, and then use it in your ODBC orJDBC application to connect to Google Analytics. The procedure for using aconnection string or URL in an application varies depending on the application. Fordetailed instructions, see the product documentation for your application.

Note:

On Windows and macOS, you can use the Connection Assistant to automaticallygenerate connection strings and URLs for all your GDSNs. You can copy thesestrings or URLs, and then use them in your ODBC or JDBC applications toconnect to your data source. For more information, see the Magnitude GatewayUser Guide.

Each connection string or URL consists of multiple connection property settings thatare separated by semicolons (;). Each setting consists of a property name, an equalsign (=), and a value.

The string or URL must start with a component that specifies which database driver touse for the connection:

l ODBC connection strings use the following property setting to specify theUniversal ODBC Driver:

Driver=Magnitude Universal ODBC Driver;

l JDBC connection URLs use the following prefix to specify the Universal JDBCDriver:

jdbc:gateway://

You can write a string or URL that specifies a GDSN, a DSN (for ODBC connectionsonly), a set of connection properties, or a combination of these. If the same connectioninformation is specified in multiple places, the application processes the informationaccording to the following precedence order:

www.simba.com 12

User Guide Writing Connection Strings and URLs forGoogle Analytics

l In ODBC applications:l Properties that are specified in a DSN take precedence over those that arespecified in a GDSN.

l Properties that are specified in a connection string take precedence overthose specified in DSNs and GDSNs.

l In JDBC applications, properties that are specified in a connection URL takeprecedence over those specified in a GDSN.

You can take advantage of this precedence order to modify a connection withoutaffecting others that use the same GDSN or DSN. For more information, see "UsingGDSNs with Additional Connection Properties" in the Magnitude Gateway User Guide.

The following are examples of connection strings that can be used to connect toGoogle Analytics:

l Examples: Connecting to Google Analytics Using a GDSN on page 13l Examples: Connecting to Google Analytics Using a GDSN and AdditionalProperties on page 16

l Examples: Connecting to Google Analytics Using a DSN and AdditionalProperties on page 17

l Examples: Connecting to Google Analytics Without Using GDSNs or DSNs onpage 18

These examples do not account for every possible configuration or use of optionalsettings. For information about all the properties that you can specify, see GoogleAnalytics Connection Properties on page 25.

Examples: Connecting to Google Analytics Using aGDSNThis section contains examples of connection strings and URLs that specify a GDSNbut do not specify any additional connection properties. When you use this type ofstring or URL to connect to Google Analytics, the connection is established based onthe connection information defined in the GDSN. For more information about GDSNs,see "Configuring GDSNs" in the Magnitude Gateway User Guide.

Depending on whether the Magnitude Gateway Google Analytics Adapter wasinstalled locally through Magnitude Gateway Desktop or on a remote server throughMagnitude Gateway Embedded Edition, you need to include different connectionproperties in your string or URL. For more information, see the sections below:

www.simba.com 13


l Example: Specifying a Local GDSN on page 14l Example: Specifying a Remote GDSN on page 14l Example: Using a GDSN UUID on page 15

Example: Specifying a Local GDSN

A local GDSN is a GDSN that is associated with an adapter that was installed on yourlocal computer through Magnitude Gateway Desktop. The following is the format of anODBC connection string that specifies a local GDSN, and the format of aJDBC connection URL that does the same:

Driver=Magnitude Universal ODBC Driver;GDSN=[GDSN_Name];

jdbc:gateway://localhost;GDSN=[GDSN_Name];

Where [GDSN_Name] is the name of a local GDSN that is defined in MagnitudeGateway Settings. For example:

Driver=Magnitude Universal ODBC Driver;GDSN=Google AnalyticsGateway Connection;

jdbc:gateway://localhost;GDSN=Google Analytics GatewayConnection;

Important:

GDSN names are case-sensitive.

Example: Specifying a Remote GDSN

A remote GDSN is a GDSN that is associated with an adapter that was installed on aremote server through Magnitude Gateway Embedded Edition. To use a remote GDSNin a connection string or URL, you must specify the GDSN name and the GatewayManagement Server instance where the GDSN is saved.

The following is the format of an ODBC connection string that specifies a remoteGDSN, and the format of a JDBC connection URL that does the same:

Driver=Magnitude Universal ODBC Driver;GMSHost=[Management_Host];GMSPort=[Management_Port];GDSN=[GDSN_Name];

jdbc:gateway://[Management_Host]:[Management_Port];GDSN=[GDSN_Name];

www.simba.com 14


Where:

l [Management_Host] is the IP address or FQDN of the management server.l [Management_Port] is the number of the TCP port that the management serveruses to listen for connections.

l [GDSN_Name] is the name of the GDSN.

Important:

GDSN names are case-sensitive.

For example:

Driver=Magnitude Universal ODBCDriver;GMSHost=192.168.222.160;GMSPort=9999;GDSN=GoogleAnalytics Gateway Connection;

jdbc:gateway://192.168.222.160:9999;GDSN=Google AnalyticsGateway Connection;

Using the Display Name

You also have the option of specifying the display name of the management serverinstead of its host and port information.

To use the display name in an ODBC connection string, set the GMS connectionproperty.

For example:

Driver=Magnitude Universal ODBCDriver;GMS=MyManagementServer;GDSN=Google Analytics GatewayConnection;

To use the display name in a JDBC connection URL, specify the display name inplace of the host and port information, after the gateway:// prefix.

For example:

jdbc:gateway://MyManagementServer;GDSN=Google AnalyticsGateway Connection;

Example: Using a GDSN UUID

As an alternative, you can specify a GDSN using its UUID instead of its name, so thatyour connections remain valid even if the GDSN is renamed. To do this, set the GDSN_

www.simba.com 15


UUID property.

The UUID of a GDSN can be found in Magnitude Gateway Settings, on the Primary tabfor the GDSN. For more information, see "Viewing GDSN UUIDs" in the MagnitudeGateway User Guide.

For example:

Driver=Magnitude Universal ODBC Driver;GDSN_UUID=JMVIHEKWERIPO56T6W72IHCGIOH5UKWL;

jdbc:gateway://192.168.222.160:9999;GDSN_UUID=JMVIHEKWERIPO56T6W72IHCGIOH5UKWL;

Important:

GDSN UUIDs are case-sensitive.

Examples: Connecting to Google Analytics Using aGDSN and Additional PropertiesWhen the same connection properties are specified in a DSN and in the string or URLthat refers to it, the settings in the string or URL take precedence. This section containsexamples of connection strings and URLs that override GDSN settings by specifyingone or more connection properties.

Note:

These examples specify local GDSNs using their names. For information aboutspecifying remote GDSNs, or using UUIDs instead of names, see Examples:Connecting to Google Analytics Using a GDSN on page 13.

The following is the format of an ODBC connection string that specifies connectionproperties in addition to specifying a GDSN, and the format of a JDBC connectionURL that does the same:

Driver=Magnitude Universal ODBC Driver;GDSN=[GDSN_Name];[Property1]=[Value1];[Property2]=[Value2];...

jdbc:gateway://localhost;GDSN=[GDSN_Name];[Property1]=[Value1];[Property2]=[Value2];...

The placeholders are defined as follows:

www.simba.com 16


l [GDSN_Name] is the name of the GDSN.l [Property1] and [Property2] are key names for connection properties that theadapter supports, and [Value1] and [Value2] are the values that you want to setthose properties to. You can set any number of connection properties. Forinformation about all the connection properties that the Magnitude GatewayGoogle Analytics Adapter supports, see Google Analytics Connection Propertieson page 25.

For example, the following string and URL both route the connection through a proxyserver, but otherwise work the same way as other connections that use the "GoogleAnalytics Gateway Connection" GDSN:

Driver=Magnitude Universal ODBC Driver;GDSN=Google AnalyticsGateway Connection;ProxyHost=192.168.222.160;ProxyPort=8000;

jdbc:gateway://localhost;GDSN=Google Analytics GatewayConnection;ProxyHost=192.168.222.160;ProxyPort=8000;

Examples: Connecting to Google Analytics Using aDSN and Additional PropertiesFor ODBC connections specifically, you can specify connection properties in a DSN.When the same connection properties are specified in a GDSN and the DSN thatrefers to it, the settings in the DSN take precedence. Additionally, when the sameconnection properties are specified in a DSN and the connection string that refers to it,the properties in the string take precedence.

This section contains examples of connection strings that override GDSN settingsusing a combination of DSN and connection string settings.

Note:

These examples specify local GDSNs using their names. For information aboutspecifying remote GDSNs, or using UUIDs instead of names, see Examples:Connecting to Google Analytics Using a GDSN on page 13.

You can replicate the connection from Examples: Connecting to Google AnalyticsUsing a GDSN and Additional Properties on page 16 by creating a DSN that refers tothe "Google Analytics Gateway Connection" GDSN and also specifiesProxyHost=192.168.222.160 and ProxyPort=8000. You would then use thatDSN directly in your ODBC application, or write a connection string that specifies thatDSN.

www.simba.com 17


For example, if you created a DSN named "Proxy Gateway Connection" that refers tothe "Google Analytics Gateway Connection" GDSN and specifies the proxy settingsdescribed above, then the following connection string would establish the exact sameconnection as the string in Examples: Connecting to Google Analytics Using aGDSN and Additional Properties on page 16:

Driver=Magnitude Universal ODBC Driver;DSN=Proxy GatewayConnection;

Additionally, you can override both the DSN and GDSN settings by specifyingconnection properties directly in the connection string. This enables you to modify aconnection even further without affecting other connections that use the same DSN orGDSN.

For example, this string connects to the proxy server using a different port number, butdoes not affect the port number for other connections that use the "Proxy GatewayConnection" DSN or the "Google Analytics Gateway Connection" GDSN:

Driver=Magnitude Universal ODBC Driver;DSN=Proxy GatewayConnection;ProxyPort=5000;

For information about all the connection properties that the Magnitude GatewayGoogle Analytics Adapter supports, see Google Analytics Connection Properties onpage 25.

Examples: Connecting to Google Analytics WithoutUsing GDSNs or DSNsThis section contains examples of connection strings and URLs that specify all thenecessary connection settings so that GDSNs and DSNs are not required.

Because this type of string or URL does not specify a GDSN or DSN, it must include aproperty setting to indicate which Magnitude Gateway adapter to use for theconnection. You can specify the Magnitude Gateway Google Analytics Adapter bysetting the Adapter property to googleanalytics, or by setting the Adapter_UUID property to the UUID of the adapter. For more information about adapter UUIDs,see "Viewing Adapter UUIDs" in the Magnitude Gateway User Guide.

Note:

Adapter UUIDs are case-sensitive.

Depending on whether the Magnitude Gateway Google Analytics Adapter wasinstalled locally through Magnitude Gateway Desktop or on a remote server through

www.simba.com 18


Magnitude Gateway Embedded Edition, you need to include different connectionproperties in your string or URL. For more information, see the sections below:

l Example: Specifying a Local Adapter on page 19l Example: Specifying a Remote Adapter on page 20l Example: Using an Adapter UUID on page 22l Additional Examples on page 22

Example: Specifying a Local Adapter

A local adapter is an adapter that was installed on your local computer throughMagnitude Gateway Desktop. The following is the format of an ODBC connectionstring that can connect to a data source without using a GDSN or DSN, and the formatof a JDBC connection URL that does the same. In both cases, a local adapter isspecified.

Driver=Magnitude Universal ODBCDriver;Adapter=googleanalytics;[Property1]=[Value1];[Property2]=[Value2];...

jdbc:gateway://localhost;Adapter=googleanalytics;[Property1]=[Value1];[Property2]=[Value2];...

Where [Property1] and [Property2] are key names for connection properties that theadapter supports, and [Value1] and [Value2] are the values that you want to set thoseproperties to. You can set any number of connection properties. In most cases, thereare several properties that you must set in order to successfully connect to the datasource.

For example, to specify the minimum set of properties for connecting to GoogleAnalytics using a client ID and client secret:

Driver=Magnitude Universal ODBCDriver;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;

jdbc:gateway://localhost;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_

www.simba.com 19


Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;


Example: Specifying a Remote Adapter

A remote adapter is an adapter that was installed on a remote server throughMagnitude Gateway Embedded Edition. To specify a remote adapter in a connectionstring or URL that does not include a GDSN, you must specify the adapter name andthe Gateway Management Server instance that the adapter is associated with.

The following is the format of an ODBC connection string that can connect to a datasource without using a GDSN, and the format of a JDBC connection URL that does thesame. In both cases, a remote adapter is specified.

Driver=Magnitude Universal ODBC Driver;GMSHost=[Management_Host];GMSPort=[Management_Port];Adapter=googleanalytics;[Property1]=[Value1];[Property2]=[Value2];...

jdbc:gateway://[Management_Host]:[Management_Port];Adapter=googleanalytics;[Property1]=[Value1];[Property2]=[Value2];...

Where:

l [Management_Host] is the IP address or FQDN of the management server.l [Management_Port] is the number of the TCP port that the management serveruses to listen for connections.

l [Property1] and [Property2] are key names for connection properties that theadapter supports, and [Value1] and [Value2] are the values that you want to setthose properties to. You can set any number of connection properties. In mostcases there are several properties that you must set in order to successfullyconnect to the data source.

For example, to specify the minimum set of properties for connecting to GoogleAnalytics using client ID and client secret:

Driver=Magnitude Universal ODBC

www.simba.com 20


Driver;GMSHost=192.168.222.160;GMSPort=9999;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;

jdbc:gateway://192.168.222.160:9999;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;


Using the Display Name

You also have the option of specifying the display name of the management serverinstead of its host and port information.

To use the display name in an ODBC connection string, set the GMS connectionproperty.

For example:

Driver=Magnitude Universal ODBCDriver;GMS=MyManagementServer;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;

To use the display name in a JDBC connection URL, specify the display name inplace of the host and port information, after the gateway:// prefix.

For example:

www.simba.com 21


jdbc:gateway://MyManagementServer;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;

Example: Using an Adapter UUID

As an alternative, you can specify the adapter using its UUID instead of its name. Todo this, set the Adapter_UUID property.

For example:

Driver=Magnitude Universal ODBCDriver;GMSHost=192.168.222.160;GMSPort=9999;Adapter_UUID=B3090EA755764825871FCC2EE7D5A875;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;

jdbc:gateway://localhost;Adapter_UUID=B3090EA755764825871FCC2EE7D5A875;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;

Additional Examples

The following are a few example connection strings and URLs that meet therequirements described in Connecting to Google Analytics on page 8. In theseexamples, a local adapter is specified by name.

l Specifying the minimum set of properties for connecting to Google Analyticsusing an access token:

Driver=Magnitude Universal ODBCDriver;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_

www.simba.com 22


AccessToken=N9PcyQ9prK4LvUMMMpFL4R+lVE=;ViewID=123456;

jdbc:gateway://localhost;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_AccessToken=N9PcyQ9prK4LvUMMMpFL4R+lVE=;ViewID=123456;

l Connecting to Google Analytics through a proxy server that requiresauthentication:

Driver=Magnitude Universal ODBCDriver;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;ProxyHost=192.168.222.160;ProxyPort=8000;ProxyUid=jsmith;ProxyPwd=admin12345;

jdbc:gateway://localhost;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;ProxyHost=192.168.222.160;ProxyPort=8000;ProxyUid=jsmith;ProxyPwd=admin12345;

l Connecting to Google Analytics through a proxy server, with the adapterretrieving the proxy server information from the Internet Options in InternetExplorer:

Driver=Magnitude Universal ODBCDriver;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;UseWindowsProxySettings=1;

www.simba.com 23


jdbc:gateway://localhost;Adapter=googleanalytics;Auth_Type=OAuth_2.0;Auth_Client_ID=u674kn9Pcyq9pr4labcrapfl4rive;Auth_Client_Secret=45kn9Pcyq9pr4lvu123pfl4r57;Auth_Scope=https://www.googleapis.com/auth/analytics.readonly;Auth_BaseRedirectURI=http://example.googleapis.com;ViewID=123456;UseWindowsProxySettings=1;

www.simba.com 24


Google Analytics Connection Properties

The connection properties that are available when you use the Magnitude GatewayGoogle Analytics Adapter are listed and described below. The properties arecategorized according to the Magnitude Gateway Settings tab where they areavailable, and then listed in the top-down order in which they appear on the tab.

l Primary Connection Properties on page 27l Proxy Connection Properties on page 31l SSL Connection Properties on page 33l Optimizations Connection Properties on page 35

Each property is identified by a property name as well as a key name. When creating aGDSN, refer to the property names and set the properties using the fields, checkboxes, and drop-down lists available in Magnitude Gateway Settings. When settingproperties in a DSN, connection string, or connection URL, refer to the key names andthe values that are enclosed in parentheses in the property descriptions.

For a summary of how the property names and key names are mapped to each other,see Key Names of Google Analytics Connection Properties on page 25.

Key Names of Google Analytics ConnectionPropertiesThe following tables map each connection property name to its corresponding keyname. The properties are categorized by use case and then listed alphabetically withineach category.

Primary Properties Key Names

For detailed information about these properties, see Primary Connection Properties onpage 27.


Access Token Auth_AccessToken


Client ID Auth_Client_ID

www.simba.com 25

User Guide Google Analytics Connection Properties


Client Secret Auth_Client_Secret

Description None

Name None

Redirect URI Auth_BaseRedirectUri

Scopes Auth_Scopes

ViewID ViewID

Proxy Properties Key Names

For detailed information about these properties, see Proxy Connection Properties onpage 31.



Proxy Password ProxyPwd


Proxy User ID ProxyUid

Use Windows Proxy Settings UseWindowsProxySettings

SSL Properties Key Names

For detailed information about these properties, see SSL Connection Properties onpage 33.


Use Host Verification UseHostVerification

Use Peer Verification UsePeerVerification

www.simba.com 26


Optimizations Properties Key Names

For detailed information about these properties, see Optimizations ConnectionProperties on page 35.


Data Compression EncodingType

Double Buffering EnableDoubleBuffer

Primary Connection PropertiesThe following connection properties are available on the Primary tab in MagnitudeGateway Settings when you configure a Google Analytics GDSN. Use these propertiesto specify basic connection information such as which Google Analytics data source toconnect to.

The properties are listed in the top-down order in which they appear on the Primarytab:

l Name on page 27l Description on page 28l Authentication Method on page 28l Client ID on page 29l Client Secret on page 29l Redirect URI on page 29l Scopes on page 30l View ID on page 30l Access Token on page 30

Name

Key Name Default Value Required

None None Only if creating a GDSN.

Description

In this field, type a name that uniquely identifies the GDSN. You can then refer to thisname when creating an ODBC DSN or writing a connection string or URL in order touse the property settings defined in this GDSN.

www.simba.com 27


This property cannot be set in a connection string or URL. You can set it only whenyou create a new GDSN in Magnitude Gateway Settings.

Description


None None No

Description

In this field, type a description for the GDSN. For example, if the GDSN is set up for aspecific use case, you might include a note to remind yourself and others of this.

This property cannot be set in a connection string or URL. You can set it only whenyou configure a GDSN in Magnitude Gateway Settings.

Authentication Method


Auth_Type OAuth (OAuth_2.0) Yes

Description

Set this property to one of the following values, to control whether the adapterauthenticates the connection to Google Analytics by using an access token or by usinga client ID and client secret to obtain and use an access token.

l Access Token (OAuth_2.0): The adapter uses an access token in order tosuccessfully connect to Google Analytics.

l OAuth (OAuth_2.0): The adapter uses a client ID, client secret, redirect URI,scope, and view ID in order to successfully connect to Google Analytics.

Note:

We recommend that you connect to Google Analytics using a client ID and clientsecret instead of an access token. Access tokens expire after a certain amount oftime, potentially causing connections to stop working unexpectedly. When youconnect using a client ID and client secret, the adapter always retrieves a validaccess token at connection time.

www.simba.com 28


Client ID


Auth_Client_ID None Only if AuthenticationMethod is set to OAuth.

Description

Set this property to the client ID associated with your Google Analytics application. Theadapter uses this value (with a client secret, redirect URI, scope, and view ID) toauthenticate the connection to Google Analytics.

This can be found by logging in to the Google API console, and clicking Credentials.The ID will be listed here, or you can create a new one.

Client Secret


Auth_Client_Secret None Only if AuthenticationMethod is set to OAuth.

Description

Set this property to the client secret associated with your Google Analytics application.The adapter uses this value (with a client ID, redirect URI, scope, and view ID) toauthenticate the connection to Google Analytics.

This can be found by logging in to the Google API console, and clicking Credentials >[Name of the credential]. The Secret will be listed here, or you can create a new one.

Redirect URI


Auth_BaseRedirectUri

None Only if AuthenticationMethod is set to OAuth.

Description

Set this property to the redirect URI associated with your Google Analytics application.

www.simba.com 29


Scopes


Auth_Scope None Only if AuthenticationMethod is set to OAuth.

Description

Set this property to the scope that you want the adapter to request when retrieving anaccess token. The scope associated with an access token determines the type of datathat you are allowed to retrievewhen you connect to Google Analytics using thataccess token.

Currently, the only scope supported ishttps://www.googleapis.com/auth/analytics.readonly.

View ID


ViewID None Yes

Description

Set this property to Google Analytics view ID.

This can be found by logging in to the Google Analytics administration page, andclicking ADMIN > [Select your Account Property and View] > View Settings.

Access Token


Auth_AccessToken None Only if AuthenticationMethod is set to Access

Token.

Description

Set this property to the access token associated with your Google Analyticsapplication. The adapter uses this value to authenticate the connection.

www.simba.com 30


Proxy Connection PropertiesThe following connection properties are available on the Proxy tab in MagnitudeGateway Settings when you configure a Google Analytics GDSN. Use these propertiesto configure Google Analytics connections that go through a proxy server.

The properties are listed in the top-down order in which they appear on the Proxy tab:

l Use Windows Proxy Settings on page 31l Proxy Host on page 31l Proxy Port on page 32l Proxy User ID on page 32l Proxy Password on page 33

Use Windows Proxy Settings


UseWindowsProxySettings Disabled (0) No

Description

Note:

This property is used only when you are connecting from a Windows computer.

Enable or disable this property to control whether the adapter uses the proxy serverinformation from the GDSN settings or from the Internet Options in Internet Explorer.

l Enabled (1): The adapter uses the proxy server information from the InternetOptions in Internet Explorer.

l Disabled (0): The adapter uses the proxy server information specified by theProxy Host, Proxy Port, Proxy User ID, and Proxy Password settings. For moreinformation, see below.

Proxy Host


ProxyHost None Only if connectingthrough a proxy serverand Use Windows ProxySettings is disabled.

www.simba.com 31


Description

Note:

This property is used only when the Use Windows Proxy Settings property isdisabled.

Set this property to the host name or IP address of the proxy server that you want toconnect through. This setting determines which server the adapter uses as a proxy forthe connection.

Proxy Port


ProxyPort None Only if connectingthrough a proxy serverand Use Windows ProxySettings is disabled.

Description

Note:


Set this property to the number of the TCP port that the proxy server uses to listen forconnections. This setting determines which port on the proxy server the adapterconnects to.

Proxy User ID


ProxyUid None Only if connectingthrough a proxy server

that requiresauthentication, and UseWindows Proxy Settings

is disabled.

www.simba.com 32


Description

Note:


Set this property to the user name that you use to access the proxy server. This settingdetermines which user name the adapter uses to authenticate the connection throughthe proxy server.

Proxy Password


ProxyPwd None Only if connectingthrough a proxy server

that requiresauthentication, and UseWindows Proxy Settings

is disabled.

Description

Note:


Set this property to the password that you use to access the proxy server. This settingdetermines which password the adapter uses to authenticate the connection throughthe proxy server.

SSL Connection PropertiesThe following connection properties are available on the SSL tab in MagnitudeGateway Settings when you configure a Google Analytics GDSN. Use these propertiesto configure SSL encryption and identity verification for the connection.

www.simba.com 33


Note:

In this documentation, "SSL" refers to both TLS (Transport Layer Security) andSSL (Secure Sockets Layer). The adapter supports up to TLS 1.2. The SSL/TLSversion used for the connection is the highest version that is supported by both theadapter and the data source.

The properties are listed in the top-down order in which they appear on the SSL tab:

l Use Host Verification on page 34l Use Peer Verification on page 34

Use Host Verification


UseHostVerification l Enabled (1) onWindows.

l Disabled (0) onmacOS and Linux.

No

Description

Enable or disable this property to control whether the adapter requires the host namein the server's certificate to match the host name of the server when connecting overSSL.

l Enabled (1): The adapter requires the host name in the server's certificate tomatch the host name of the server that you are connecting to.

l Disabled (0): The adapter accepts all host names.

Use Peer Verification


UsePeerVerification l Enabled (1) onWindows.

l Disabled (0) onmacOS and Linux.

No

Description

Enable or disable this property to control whether the adapter verifies the identify of theserver when connecting over SSL.

www.simba.com 34


l Enabled (1): The adapter verifies the identity of the server.l Disabled (0): The adapter does not verify the identity of the server.

Optimizations Connection PropertiesThe following connection properties are available on the Optimizations tab inMagnitude Gateway Settings when you configure a Google Analytics GDSN. Usethese properties to configure adapter features that may improve adapter performance.

The properties are listed in the top-down order in which they appear on theOptimizations tab:

l Double Buffering on page 35l Data Compression on page 35

Double Buffering


EnableDoubleBuffer Disabled (0) No

Description

Enable or disable this property to control whether the adapter retrieves GoogleAnalytics data using double-buffering. If the transfer speed of your network is higherthan the data processing speed of the adapter, then you can optimize performance byenabling this property. However, be aware that when double-buffering is enabled, theadapter might consume more memory and resources.

l Enabled (1): The adapter retrieves data using double-buffering.l Disabled (0): The adapter retrieves data using single-buffering.

Data Compression


EncodingType Enabled (No key valuespecified)

No

Description

Enable or disable this property to control whether the adapter compresses data whenthe data is passed between the adapter and the Google Analytics data source. To

www.simba.com 35


optimize performance, enable this property.

l Enabled (No key value specified): The adapter compresses the data, using thesupported compression method that best compresses the data.

l Disabled (OFF): The adapter does not compress the data.

www.simba.com 36


Google Analytics Stored Procedures

The Magnitude Gateway Google Analytics Adapter provides stored procedures thatyou can use to create, view, modify, and delete objects from a Google Analytics datasource.

For a list of the available stored procedures, including detailed information about eachstored procedure, see the Magnitude Gateway Google Analytics Adapter ReferenceGuide.

Important:

The adapter currently does not support stored procedures for JDBC connections.These stored procedures cannot be used when you connect to Google Analyticsthrough a JDBC application.

www.simba.com 37

User Guide Google Analytics Stored Procedures

Google Analytics Schema Tables

Google Analytics stores data in structures which do not follow the rules of data typingand structure that apply to traditional relational tables and columns. Becausetraditional ODBC and JDBC toolsets might not support these data structures, the dataneeds to be mapped to a relational form. To achieve this, the Magnitude GatewayGoogle Analytics Adapter uses schema tables to map the Google Analytics data toformats that are compatible with ODBC and JDBC. For a list of the available schematables, including detailed information about each table, see the Magnitude GatewayGoogle Analytics Adapter Reference Guide.

www.simba.com 38

User Guide Google Analytics Schema Tables

Third-Party Trademarks

Linux is the registered trademark of Linus Torvalds in Canada, United States and/orother countries.

Mac, macOS, Mac OS, and OS X are trademarks or registered trademarks of Apple,Inc. or its subsidiaries in Canada, United States and/or other countries.

Microsoft, MSDN, Windows, Windows Server, Windows Vista, and the Windows startbutton are trademarks or registered trademarks of Microsoft Corporation or itssubsidiaries in Canada, United States and/or other countries.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other namesmay be trademarks of their respective owners.

Google Analytics and Google are trademarks or registered trademarks of Google, Inc.or its subsidiaries in Canada, the United States and/or other countries.

All other trademarks are trademarks of their respective owners.

www.simba.com 39

User Guide Third-Party Trademarks

magnitudegatewaygoogle analyticsadapter userguide · magnitude gateway google analytics adapter...

Documents