Skip to content

Commit 886dc43

Browse files
maxi297brianjlaikatmarkham
authored
[ISSUE #72] LinkedIn Ads documentation (#30386)
Co-authored-by: brianjlai <[email protected]> Co-authored-by: katmarkham <[email protected]>
1 parent fca0b6f commit 886dc43

File tree

2 files changed

+164
-0
lines changed

2 files changed

+164
-0
lines changed

‎docs/snowflake-native-apps/linkedin-ads-ui.gif

1.16 MB
Loading

‎docs/snowflake-native-apps/linkedin-ads.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# LinkedIn Ads Connector
2+
3+
The LinkedIn Ads Connector by Airbyte is a Snowflake Native Application that allows you to extract data from your LinkedIn Ads account and load records into a Snowflake database of your choice.
4+
5+
![](./linkedin-ads-ui.gif)
6+
7+
> **Info**
8+
> The LinkedIn Ads Connector is in _private preview_ and is subject to further development that may affect setup and configuration of the application.
9+
10+
# Getting started
11+
12+
## Prerequisites
13+
A LinkedIn Ads account with permission to access data from accounts you want to sync.
14+
15+
## Installing the App
16+
17+
> **Warning**
18+
> Do not refresh the Apps page while the application is being installed. This may cause installation to fail.
19+
20+
1. Log into your Snowflake account.
21+
2. On the left sidebar, click `Marketplace`.
22+
3. Search for `Linkedin Ads Connector` by Airbyte or navigate to https://app.snowflake.com/marketplace/listing/GZTYZ9BCRSJ/airbyte-linkedin-ads-connector-by-airbyte
23+
4. Click `Request`. This will send a request that we will manually service as soon as we can.
24+
5. On the left sidebar, click `Apps`.
25+
6. Under the `Recently Shared with You` section, you should see the `Linkedin Ads Connector by Airbyte`. Click `Get`.
26+
7. Expand `Options`.
27+
1. You can rename the application or leave the default. This is how you will reference the application from a worksheet.
28+
2. Specify the warehouse that the application will be installed to.
29+
8. Click `Get`.
30+
9. Wait for the application to install. Once complete, the pop-up window should automatically close.
31+
32+
You should now see the LinkedIn Ads Connector by Airbyte application under `Installed Apps`. You may need to refresh the page.
33+
34+
## LinkedIn Ads Account
35+
In order for the Snowflake Native App to query LinkedIn Ads, you will need an account with the right permissions. Please follow [the LinkedIn Ads authentication guide](https://docs.airbyte.com/integrations/sources/linkedin-ads/#set-up-linkedin-ads-authentication-airbyte-open-source) for further information.
36+
37+
## Snowflake Native App Authorizations
38+
> **Note**
39+
> By default the app will be installed using the name `AIRBYTE_LINKEDIN_ADS`, but if you renamed the app during installation, you will have to use that name as a reference.
40+
41+
1. Create the database where the app will access the authorization. This database can be different from the database where the sync will output records.
42+
```
43+
CREATE DATABASE <database>;
44+
USE <database>;
45+
```
46+
47+
2. The native app will validate the output database and create it if it does not exist. In order to do that, the app needs access to the database:
48+
```
49+
GRANT CREATE DATABASE ON ACCOUNT TO APPLICATION <app_name>;
50+
```
51+
52+
3. You will need to allow outgoing network traffic based on the domain of the source. In the case of LinkedIn Ads, simply run:
53+
```
54+
CREATE OR REPLACE NETWORK RULE linkedin_apis_network_rule
55+
MODE = EGRESS
56+
TYPE = HOST_PORT
57+
VALUE_LIST = ('api.linkedin.com', 'www.linkedin.com', 'linkedin.com');
58+
```
59+
60+
> **Note**
61+
> As of 2023-09-13, the [Snowflake documentation](https://docs.snowflake.com/en/sql-reference/sql/create-external-access-integration) mentions that direct external access is a preview feature and that it is `available to all accounts on AWS` which might restrict the number of users able to use the connector.
62+
63+
4. Once you have external access configured, you need define your authorization/authentication. Provide the credentials to the app as such:
64+
```
65+
CREATE OR REPLACE SECRET integration_linkedin_ads_oauth
66+
TYPE = GENERIC_STRING
67+
SECRET_STRING = '{
68+
"auth_method": "oAuth2.0",
69+
"client_id": <client_id>,
70+
"client_secret": <client_secret>,
71+
"refresh_token": <refresh_token>
72+
}';
73+
```
74+
... where `client_id`, `client_secret` and `refresh_token` are strings. For more information, see the [LinkedIn Ads authentication guide](https://docs.airbyte.com/integrations/sources/linkedin-ads/#set-up-linkedin-ads-authentication-airbyte-open-source).
75+
76+
5. Once the network rule and the secret are defined in Snowflake, you need to make them available to the app by using an external access integration.
77+
```
78+
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION integration_linkedin_ads
79+
ALLOWED_NETWORK_RULES = (linkedin_apis_network_rule)
80+
ALLOWED_AUTHENTICATION_SECRETS = (integration_linkedin_ads_oauth)
81+
ENABLED = true;
82+
```
83+
84+
6. Grant permission for the app to access the integration.
85+
```
86+
GRANT USAGE ON INTEGRATION integration_linkedin_ads TO APPLICATION AIRBYTE_LINKEDIN_ADS;
87+
```
88+
89+
7. Grant permissions for the app to access the database that houses the secret and read the secret.
90+
```
91+
GRANT USAGE ON DATABASE <your_database> TO APPLICATION AIRBYTE_LINKEDIN_ADS;
92+
GRANT USAGE ON SCHEMA <your_schema> TO APPLICATION AIRBYTE_LINKEDIN_ADS;
93+
GRANT READ ON SECRET integration_linkedin_ads_oauth TO APPLICATION AIRBYTE_LINKEDIN_ADS;
94+
```
95+
96+
97+
## Configure a connection
98+
Once this is all set up, you can now configure a connection. To do so, use the Streamlit app by going in the `Apps` section and selecting `AIRBYTE_LINKEDIN_ADS`. You will have to accept the Anaconda terms in order to use Streamlit. Once you have access to the app, select `New Connection` and fill the following fields:
99+
100+
---
101+
102+
`Secret`
103+
104+
The name of the secret prefixed by which database and schema. Based on the previous steps: `<database>.<your_schema>.integration_linkedin_ads_oauth`.
105+
106+
---
107+
108+
`External Access Integration`
109+
110+
Name of the Snowflake integration where the secret and network rules are configured. Based on the previous steps: `integration_linkedin_ads`.
111+
112+
---
113+
114+
`start_date`
115+
116+
UTC date in the format 2020-09-17. Any data before this date will not be replicated.
117+
118+
---
119+
120+
`account_ids`
121+
122+
Leave empty, if you want to pull the data from all associated accounts. To specify individual account IDs to pull data from, separate them by a space. See the [LinkedIn Ads docs](https://www.linkedin.com/help/linkedin/answer/a424270/find-linkedin-ads-account-details) for more info.
123+
124+
---
125+
126+
`Output Database`
127+
128+
The database where the records will be saved. Snowflake's database naming restriction applies here.
129+
130+
---
131+
132+
`Output Schema`
133+
134+
The table where the schema will be saved. Snowflake's table naming restriction applies here.
135+
136+
---
137+
138+
`Connection name`
139+
140+
How the connection will be referred in the Streamlit app.
141+
142+
---
143+
144+
`Replication Frequency`
145+
146+
How often records are fetched.
147+
148+
---
149+
150+
## Run a sync
151+
Once a connection is configured, go in `Connections List` and click on `Sync Now` for the connection you want to sync. Once the sync is complete, you should be able to validate that the records have been stored in `<your_database>.<your_schema>`
152+
153+
### Supported Streams
154+
As of now, all supported streams perform a full refresh. Incremental syncs are not yet supported. Here are the list of supported streams:
155+
* Accounts
156+
* Account Users
157+
* Ad Analytics by Campaign
158+
* Ad Analytics by Creative
159+
* Campaigns
160+
* Campaign Groups
161+
* Creatives
162+
163+
# Contact Us
164+
[email protected]

0 commit comments

Comments
 (0)