Add AdMob UMP/CMP API code examples & gotchas

markdown/guide/programming/01/index.markdown

@@ -43,7 +43,6 @@ If you don't already have a favorite text editor, the following options are reco
 Editor																Add-On Package																					 macOS		 Windows
 ------------------------------------------------------------------	----------------------------------------------------------------------------------------------	----------	----------
 [Sublime Text](https://www.sublimetext.com)							[Solar2D Editor](https://github.com/coronalabs/CoronaSDK-SublimeText)	     					 ✓	 ✓
-[Atom](https://atom.io)												[autocomplete-corona](https://atom.io/packages/autocomplete-corona)	    					     ✓	 ✓
 [Visual Studio Code](https://code.visualstudio.com/)				[Solar2d Autocomplete](https://bit.ly/3IfNx6e)	    											 ✓	 ✓
 [Xcode](https://developer.apple.com/xcode/)							[Xcode Editor](https://github.com/jcbnlsn/Xcode-Corona-Editor)									 ✓
 [Vim](https://www.vim.org)																																			 ✓	 ✓

markdown/guide/start/installMac/index.markdown

@@ -124,7 +124,6 @@ You'll need a text editor or IDE to write code for your CORONA_CORE_PRODUCT proj
 Editor																Add-On Package
 ------------------------------------------------------------------	---------------------------------------------
 [Sublime Text](https://www.sublimetext.com)							[Solar2D Editor](https://github.com/coronalabs/CoronaSDK-SublimeText)
-[Atom](https://atom.io)												[autocomplete-corona](https://atom.io/packages/autocomplete-corona)
 [Visual Studio Code](https://code.visualstudio.com/)				[Solar2d-companion](https://marketplace.visualstudio.com/items?itemName=M4adan.solar2d-companion)
 [Xcode](https://developer.apple.com/xcode/)							[Xcode Editor](https://github.com/jcbnlsn/Xcode-Corona-Editor)
 [ZeroBrane Studio](https://studio.zerobrane.com)
@@ -158,7 +157,7 @@ The CORONA_CORE_PRODUCT Simulator for macOS features the following basic menu it
 
 * The standard macOS application menu provides access to the Simulator __Preferences__. It also lets you manually open/run __Corona Live Server__ for doing [Live Builds][guide.distribution.liveBuild] on actual devices.
 
-* The __File__ menu is where projects (applications) are created or opened. This is also where you __build__ your apps for distribution or testing on devices. 
+* The __File__ menu is where projects (applications) are created or opened. This is also where you __build__ your apps for distribution or testing on devices.
 
 * The __Hardware__ menu is used to simulate physical device actions such as rotating the screen.
 

markdown/guide/start/installWin/index.markdown

@@ -90,7 +90,6 @@ You'll need a text editor or IDE to write code for your CORONA_CORE_PRODUCT proj
 Editor																Add-On Package
 ------------------------------------------------------------------	---------------------------------------------
 [Sublime Text](https://www.sublimetext.com)							[CORONA_CORE_PRODUCT Editor](https://github.com/coronalabs/CoronaSDK-SublimeText)
-[Atom](https://atom.io)												[autocomplete-corona](https://atom.io/packages/autocomplete-corona)
 [Visual Studio Code](https://code.visualstudio.com/)				[CORONA_CORE_PRODUCT-companion](https://marketplace.visualstudio.com/items?itemName=M4adan.solar2d-companion)
 [Notepad++](https://notepad-plus-plus.org)
 [ZeroBrane Studio](https://studio.zerobrane.com)

markdown/plugin/admob/getConsentFormStatus.markdown

@@ -12,11 +12,19 @@
 
 ## Overview
 
-Returns two [Strings][api.type.String] `formStatus` and `consentStatus`
+Returns two [Strings][api.type.String] `formStatus` and `consentStatus`:
 
-`formStatus` can be `"available"`, `"unavailable"`, or `"unknown"`
+`formStatus` can be `"available"`, `"unavailable"`, or `"unknown"`.
 
-`consentStatus` can be `"obtained"`, `"required"`, `"notRequired"`, or `"unknown"`
+`consentStatus` can be `"obtained"`, `"required"`, `"notRequired"`, or `"unknown"`.
+
+## Gotchas
+
+* AdMob needs to initialize before you can run `admob.updateConsentForm()`.
+
+* You must wait after running `admob.updateConsentForm()` before `admob.getConsentFormStatus()` returns non-nil values.
+
+* The consent form is a legal document and underage users cannot consent to its contents. This means `formStatus` will always be `"unavailable"` for underaged users and `consentStatus` will always be `"obtained"`. AdMob does not specify what the user has consented to.
 
 
 ## Syntax
@@ -31,14 +39,20 @@ Returns two [Strings][api.type.String] `formStatus` and `consentStatus`
 local admob = require( "plugin.admob" )
 
 
--- Initialize the AdMob plugin
-
 local function adListener( event )
 
+	if ( event.phase == "init" ) then
+		-- Wait until "init" phase to update the Consent Form.
+		admob.updateConsentForm({ underage=false })
+	end
+
 end
 
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+-- Initialize the AdMob plugin.
+admob.init( adListener, { testMode=true } )
 
+-- Sometime later, get the form and consent status:
+-- (If you don't wait for the consent form to update, then both of these values will be nil.)
 local formStatus, consentStatus = admob.getConsentFormStatus()
-print("Form Status:".. formStatus .."  Consent Status: "..consentStatus)
+print( "Form Status:" .. tostring( formStatus ) .. ", Consent Status: " .. tostring( consentStatus ) )
 ``````

markdown/plugin/admob/height.markdown

@@ -45,7 +45,7 @@ local function adListener( event )
 	if ( event.phase == "init" ) then  -- Successful initialization
 		-- Load an AdMob banner ad
 		admob.load( "banner", { adUnitId="YOUR_ADMOB_AD_UNIT_ID" } )
-        
+
 	elseif ( event.phase == "loaded" ) then
 		if ( event.type == "banner" ) then  -- Banner ad is loaded
 			bannerHeight = admob.height()  -- Get the loaded banner's height
@@ -56,5 +56,5 @@ local function adListener( event )
 end
 
 -- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+admob.init( adListener, { testMode=true } )
 ``````

markdown/plugin/admob/hide.markdown

@@ -31,7 +31,7 @@ local function adListener( event )
 	if ( event.phase == "init" ) then  -- Successful initialization
 		-- Load an AdMob banner ad
 		admob.load( "banner", { adUnitId="YOUR_ADMOB_AD_UNIT_ID" } )
-        
+
 	elseif ( event.phase == "loaded" ) then
 		if ( event.type == "banner" ) then  -- Banner ad is loaded
 			-- Show a banner ad
@@ -41,7 +41,7 @@ local function adListener( event )
 end
 
 -- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+admob.init( adListener, { testMode=true } )
 
 -- Sometime later, hide the banner
 admob.hide()

markdown/plugin/admob/init.markdown

@@ -31,8 +31,8 @@ _[Table][api.type.Table]._ Table containing AdMob initialization values — see
 
 The `params` table includes parameters for AdMob initialization.
 
-##### appId ~^(required)^~
-_[String][api.type.String]._ The app ID for your app, gathered from the AdMob [dashboard](https://www.google.com/admob/).
+##### appId ~^(deprecated)^~
+_[String][api.type.String]._ The app ID for your app, gathered from the AdMob [dashboard](https://www.google.com/admob/). The appId should be set in build.settings. See [admob][plugin.admob] project settings.
 
 <div class="docs-tip-outer docs-tip-color-alert">
 <div class="docs-tip-inner-left">
@@ -82,5 +82,5 @@ local function adListener( event )
 end
 
 -- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+admob.init( adListener, { testMode=true } )
 ``````

markdown/plugin/admob/isLoaded.markdown

@@ -43,7 +43,7 @@ local function adListener( event )
 end
 
 -- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+admob.init( adListener, { testMode=true } )
 
 -- Sometime later, check if an interstitial ad is loaded
 print( admob.isLoaded( "interstitial" ) )

markdown/plugin/admob/load.markdown

@@ -90,5 +90,5 @@ local function adListener( event )
 end
 
 -- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+admob.init( adListener, { testMode=true } )
 ``````

markdown/plugin/admob/loadConsentForm.markdown

@@ -12,8 +12,15 @@
 
 ## Overview
 
-This function loads Consent Form to be displayed (if needed)
+This function loads the Consent Form to be displayed (if needed).
 
+## Gotchas
+
+* `admob.updateConsentForm()` must be run before attempting to run `admob.getConsentFormStatus()`.
+
+* You must wait after running `admob.updateConsentForm()` before `admob.getConsentFormStatus()` returns non-nil values.
+
+* The Consent Form is a legal document and underage users cannot consent to its contents. This means `formStatus` will always be `"unavailable"` for underaged users and `consentStatus` will always be `"obtained"`. AdMob does not specify what the user has consented to.
 
 ## Syntax
 
@@ -26,18 +33,25 @@ This function loads Consent Form to be displayed (if needed)
 ``````lua
 local admob = require( "plugin.admob" )
 
-
--- Initialize the AdMob plugin
 local function adListener( event )
 
-	if ( event.phase == "init" ) then  -- Successful initialization
-		local formStatus, consentStatus = admob.getConsentFormStatus()
+	if ( event.phase == "init" ) then
+		-- Wait until "init" phase to update the Consent Form.
+		admob.updateConsentForm({ underage=false })
+
+		-- Add a slight delay to allow the plugin to finish initializing and updating the Consent Form before trying to get the form.
+		timer.performWithDelay( 1000, function()
+			local formStatus, consentStatus = admob.getConsentFormStatus()
+			print( "formStatus: " .. tostring( formStatus ) .. ", consentStatus: " .. tostring( consentStatus ) )
 
-		if(formStatus == "available")then -- recommend (not required)
-			admob.loadConsentForm()
-		end
+			if (formStatus == "available") then
+				admob.loadConsentForm()
+			end
+		end )
 	end
 
 end
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+
+-- Initialize the AdMob plugin.
+admob.init( adListener, { testMode=true } )
 ``````

markdown/plugin/admob/setVideoAdVolume.markdown

@@ -44,7 +44,7 @@ local function adListener( event )
 end
 
 -- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+admob.init( adListener, { testMode=true } )
 
 -- Sometime later, mute video ads
 admob.setVideoAdVolume( 0.0 )

markdown/plugin/admob/show.markdown

@@ -67,7 +67,7 @@ local function adListener( event )
 end
 
 -- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+admob.init( adListener, { testMode=true } )
 
 -- Sometime later, show the interstitial ad
 if ( admob.isLoaded( "interstitial" ) ) then

markdown/plugin/admob/showConsentForm.markdown

@@ -12,8 +12,11 @@
 
 ## Overview
 
-This function shows Consent Form to be displayed (if loaded)
+This function shows the Consent Form to be displayed (if loaded).
 
+## Gotchas
+
+* For optimal user experience, you may wish to delay when you show the Consent Form to the user instead of showing it to them right after your app has launched and the Consent Form is available, loaded and ready to be displayed. In the example code, `timer.performWithDelay()` is used apply the delay, but you can use any other means of delaying the function calls, such as moving between scenes, showing the Consent Form before showing the first ad, etc.
 
 ## Syntax
 
@@ -26,21 +29,31 @@ This function shows Consent Form to be displayed (if loaded)
 ``````lua
 local admob = require( "plugin.admob" )
 
+local function adListener( event )
 
--- Initialize the AdMob plugin
+	if ( event.phase == "init" ) then
+		-- Wait until "init" phase to update the Consent Form.
+		admob.updateConsentForm({ underage=false })
 
-local function adListener( event )
-		if ( event.phase == "init" ) then  -- Successful initialization
+		-- Add a slight delay to allow the plugin to finish initializing and updating the Consent Form before trying to get the form.
+		timer.performWithDelay( 1000, function()
 			local formStatus, consentStatus = admob.getConsentFormStatus()
+			print( "formStatus: " .. tostring( formStatus ) .. ", consentStatus: " .. tostring( consentStatus ) )
 
-			if(formStatus == "available")then -- recommend (not required)
+			if (formStatus == "available") then
 				admob.loadConsentForm()
 			end
-		end
-		if(event.phase == "loaded" and event.type == "ump")then
+		end )
+
+		-- Successfully loading the Consent Form will trigger a "ump" type event.
+		if (event.phase == "loaded" and event.type == "ump") then
+			-- The Consent Form is available, loaded and ready to be shown.
 			admob.showConsentForm()
 		end
+	end
+
 end
 
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
+-- Initialize the AdMob plugin.
+admob.init( adListener, { testMode=true } )
 ``````

markdown/plugin/admob/updateConsentForm.markdown

@@ -12,8 +12,13 @@
 
 ## Overview
 
-This function updates Consent Manager with information that helps determine if a message needs to be displayed.
+This function updates the Consent Manager with information that helps determine if a message needs to be displayed.
 
+## Gotchas
+
+* AdMob needs to initialize before you can run `admob.updateConsentForm()`.
+
+* The Consent Form is a legal document and underage users cannot consent to its contents. This means `formStatus` will always be `"unavailable"` for underaged users and `consentStatus` will always be `"obtained"`. AdMob does not specify what the user has consented to.
 
 ## Syntax
 
@@ -43,9 +48,13 @@ local admob = require( "plugin.admob" )
 
 local function adListener( event )
 
+	if ( event.phase == "init" ) then
+		-- Wait until "init" phase to update the Consent Form.
+		admob.updateConsentForm({ underage=true, debug={ geography = "EEA", testDeviceIdentifiers={"Your-Device-Hash"} } })
+	end
+
 end
--- Initialize the AdMob plugin
-admob.init( adListener, { appId="YOUR_ADMOB_APP_ID" } )
 
-admob.updateConsentForm({ underage=true, debug={ geography = "EEA", testDeviceIdentifiers={"Your-Device-Hash"} } })
+-- Initialize the AdMob plugin
+admob.init( adListener, { testMode=true } )
 ``````