accounts config doc updates (#1096)

Adding detail and transitions around the accounts config

docs/application-settings.md

@@ -25,6 +25,7 @@ There are two ways to configure application settings: database and file. This do
 - `analytics-config.auction-events.<channel>` - defines which channels are supported by analytics for this account
 - `bid-validations.banner-creative-max-size` - Overrides creative max size validation for banners.
 
+Here are the definitions of the "purposes" that can be defined in the GDPR setting configurations:
 ```
 Purpose   | Purpose goal                    | Purpose meaning for PBS (n\a - not affected)  
 ----------|---------------------------------|---------------------------------------------
@@ -43,22 +44,26 @@ sf1       | Precise geo                     | Verifies user opt-in. If the user
 sf2       | Fingerprinting                  | n\a
 ```
 
-## File application setting
+## Setting Account Configuration in Files
 
 In file based approach all configuration stores in .yaml files, path to which are defined in application properties.
 
 ### Configuration in application.yaml
 
+The general idea is that you'll place all the account-specific settings in a separate YAML file and point to that file.
+
 ```yaml
 settings:
   filesystem:
     settings-filename: <directory to yaml file with settings>
 ```
 ### File format
 
+Here's an example YAML file containing account-specific settings:
+
 ```yaml
 accounts:
-  - id: 14062
+  - id: 1111
     bannerCacheTtl: 100
     videoCacheTtl: 100
     eventsEnabled: true
@@ -152,7 +157,7 @@ accounts:
       purpose-one-treatment-interpretation: ignore
 ```
 
-## Database application setting
+## Setting Account Configuration in the Database
 
 In database approach account properties are stored in database table.
 
@@ -171,10 +176,20 @@ settings:
     account-query: <SQL query for account>
 ```
 
-### SQL query for account requirements
+### Configurable SQL query for account requirements
+
+The general approach is that each host company can set up their database however they wish, so long as the configurable query run by
+Prebid Server returns expected data in the expected order. Here's an example configuration:
+
+```yaml
+settings:
+  database:
+    type: mysql
+    account-query: SELECT uuid, price_granularity, banner_cache_ttl, video_cache_ttl, events_enabled, enforce_ccpa, tcf_config, analytics_sampling_factor, truncate_target_attr, default_integration, analytics_config, bid_validations FROM accounts_account where uuid = ? LIMIT 1
+```
 
 The SQL query for account must:
-* return following columns, with specified type, in that order:
+* return following columns, with specified type, in this order:
     * account ID, string
     * price granularity, string
     * banner cache TTL, integer
@@ -191,7 +206,19 @@ runtime
 
 It is recommended to include `LIMIT 1` clause in the query because only the very first result returned will be taken.
 
-TCF configuration column format:
+If a host company doesn't support a given field, or they have a different table name, they can just update the query with whatever values are needed. e.g.
+
+```yaml
+settings:
+  database:
+    type: mysql
+    account-query: SELECT uuid, 'med', banner_cache_ttl, video_cache_ttl, events_enabled, enforce_ccpa, tcf_config, 0, null, default_integration, '{}', '{}' FROM myaccountstable where uuid = ? LIMIT 1
+```
+### Configuration Details
+
+#### TCF configuration JSON
+
+Here's an example of the value that the `tcf_config` column can take:
 
 ```json
 {
@@ -304,30 +331,39 @@ TCF configuration column format:
 }
 ```
 
-and bid_validations column is json with next format
+#### Bid Validations configuration JSON
+
+The `bid_validations` column is json with this format:
 
 ```json
 {
   "banner-creative-max-size": "enforce"
 }
 ```
 
+Valid values are:
+- "skip": don't do anything about creative max size for this publisher
+- "warn": if a bidder returns a creative that's larger in height or width than any of the allowed sizes, log an operational warning.
+- "enforce": if a bidder returns a creative that's larger in height or width than any of the allowed sizes, reject the bid and log an operational warning.
 
-Analytics configuration column format:
+#### Analytics Validations configuration JSON
+
+The `analytics_config`  configuration column format:
 
 ```json
 {
   "auction-events": {
-    "web": true,
-    "amp": true,
-    "app": false
+    "web": true,   // the analytics adapter should log auction events when the channel is web
+    "amp": true,   // the analytics adapter should log auction events when the channel is AMP
+    "app": false   // the analytics adapter should not log auction events when the channel is app
   }
 }
 ```
 
-#### Example
+#### Creating the accounts table
 
-Query to create accounts_account table:
+Traditionally the table name used by Prebid Server is `accounts_account`. No one remembers why. But here's SQL 
+you could use to create your table:
 
 ```sql
 'CREATE TABLE `accounts_account` (
@@ -354,12 +390,3 @@ PRIMARY KEY (`id`),
 UNIQUE KEY `uuid` (`uuid`))
 ENGINE=InnoDB DEFAULT CHARSET=utf8'
 ```
-
-Query used to get an account:
-
-```sql
-SELECT uuid, price_granularity, banner_cache_ttl, video_cache_ttl, events_enabled, enforce_ccpa, tcf_config, 
-    analytics_sampling_factor, truncate_target_attr, default_integration, analytics_config, bid_validations 
-FROM accounts_account where uuid = %ACCOUNT_ID%
-LIMIT 1
-```